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

package/README.md

@@ -13,6 +13,7 @@ It can directly control your companion's avatar in Kichi, show what it is doing,
 - Bring your OpenClaw companion into Kichi
 - Directly control the avatar's poses and actions in Kichi
 - Keep its visible state in sync while it works
+- Plan human-like idle routines during heartbeat windows
 - Let it leave notes for you in Kichi
 - Let it recommend music in Kichi
 

package/config/kichi-config.json

@@ -4,7 +4,7 @@
 			{
 				"name": "High Five",
 				"playback": "once",
-				"resumeAction": "Arms Crossed"
+				"resumeAction": "Idle Backup Hands"
 			},
 			{
 				"name": "Listen Music",
@@ -13,17 +13,17 @@
 			{
 				"name": "Arm Stretch",
 				"playback": "once",
-				"resumeAction": "Arms Crossed"
+				"resumeAction": "Idle Backup Hands"
 			},
 			{
 				"name": "Backbend Stretch",
 				"playback": "once",
-				"resumeAction": "Arms Crossed"
+				"resumeAction": "Idle Backup Hands"
 			},
 			{
 				"name": "Making Selfie",
 				"playback": "once",
-				"resumeAction": "Arms Crossed"
+				"resumeAction": "Idle Backup Hands"
 			},
 			{
 				"name": "Arms Crossed",
@@ -32,7 +32,7 @@
 			{
 				"name": "Epiphany",
 				"playback": "once",
-				"resumeAction": "Arms Crossed"
+				"resumeAction": "Idle Backup Hands"
 			},
 			{
 				"name": "Angry",
@@ -41,7 +41,7 @@
 			{
 				"name": "Yay",
 				"playback": "once",
-				"resumeAction": "Wait"
+				"resumeAction": "Idle Backup Hands"
 			},
 			{
 				"name": "Dance",
@@ -70,7 +70,7 @@
 			{
 				"name": "Curtsy",
 				"playback": "once",
-				"resumeAction": "Wait"
+				"resumeAction": "Idle Backup Hands"
 			},
 			{
 				"name": "Stand Writing",
@@ -115,7 +115,7 @@
 			{
 				"name": "No",
 				"playback": "once",
-				"resumeAction": "Arms Crossed"
+				"resumeAction": "Idle Backup Hands"
 			},
 			{
 				"name": "Panic",
@@ -124,7 +124,7 @@
 			{
 				"name": "Playful Point Up",
 				"playback": "once",
-				"resumeAction": "Arms Crossed"
+				"resumeAction": "Idle Backup Hands"
 			},
 			{
 				"name": "Rub Hands",
@@ -133,12 +133,12 @@
 			{
 				"name": "Run Jump",
 				"playback": "once",
-				"resumeAction": "Arms Crossed"
+				"resumeAction": "Idle Backup Hands"
 			},
 			{
 				"name": "Star Showing",
 				"playback": "once",
-				"resumeAction": "Arms Crossed"
+				"resumeAction": "Idle Backup Hands"
 			},
 			{
 				"name": "Walk",

package/index.ts

@@ -52,10 +52,33 @@ const MAX_NOTEBOARD_TEXT_LENGTH = 200;
 const MAX_MESSAGE_RECEIVED_PREVIEW_WIDTH = 20;
 const MAX_AGENT_END_PREVIEW_WIDTH = 10;
 const MESSAGE_RECEIVED_ELLIPSIS = "...";
+const IDLE_PLAN_POMODORO_PHASES = ["focus", "shortBreak", "longBreak", "none"] as const;
 let cachedStaticConfig: KichiStaticConfig | null = null;
 let cachedStaticConfigMtime = 0;
 let service: KichiForwarderService | null = null;
 let pluginApi: OpenClawPluginApi | null = null;
+
+type IdlePlanPomodoroPhase = typeof IDLE_PLAN_POMODORO_PHASES[number];
+type IdlePlanAction = {
+  poseType: PoseType;
+  action: string;
+  durationSeconds: number;
+  bubble: string;
+  log?: string;
+};
+type IdlePlan = {
+  requestId?: string;
+  heartbeatIntervalSeconds: number;
+  goal: string;
+  totalDurationSeconds: number;
+  stages: Array<{
+    name: string;
+    purpose: string;
+    pomodoroPhase: IdlePlanPomodoroPhase;
+    durationSeconds: number;
+    actions: IdlePlanAction[];
+  }>;
+};
 
 function isAlbumConfig(value: unknown): value is Album {
   if (!value || typeof value !== "object") {
@@ -432,9 +455,166 @@ function isClockAction(value: unknown): value is ClockAction {
   return ["set", "stop"].includes(String(value));
 }
 
+function isIdlePlanPomodoroPhase(value: unknown): value is IdlePlanPomodoroPhase {
+  return IDLE_PLAN_POMODORO_PHASES.includes(String(value) as IdlePlanPomodoroPhase);
+}
+
+function normalizeIdlePlan(value: unknown): { idlePlan?: IdlePlan; error?: string } {
+  if (!isPlainObject(value)) {
+    return { error: "idle plan payload must be an object" };
+  }
+
+  const requestId = value.requestId;
+  const heartbeatIntervalSeconds = value.heartbeatIntervalSeconds;
+  const goal = value.goal;
+  const stages = value.stages;
+
+  if (requestId !== undefined && typeof requestId !== "string") {
+    return { error: "requestId must be a string when provided" };
+  }
+  if (!isPositiveInteger(heartbeatIntervalSeconds)) {
+    return { error: "heartbeatIntervalSeconds must be a positive integer" };
+  }
+  if (typeof goal !== "string" || !goal.trim()) {
+    return { error: "goal is required" };
+  }
+  if (!Array.isArray(stages) || stages.length === 0) {
+    return { error: "stages must contain at least one stage" };
+  }
+
+  const normalizedStages: IdlePlan["stages"] = [];
+  let totalDurationSeconds = 0;
+
+  for (let stageIndex = 0; stageIndex < stages.length; stageIndex += 1) {
+    const rawStage = stages[stageIndex];
+    if (!isPlainObject(rawStage)) {
+      return { error: `stages[${stageIndex}] must be an object` };
+    }
+
+    const name = rawStage.name;
+    const purpose = rawStage.purpose;
+    const pomodoroPhase = rawStage.pomodoroPhase;
+    const durationSeconds = rawStage.durationSeconds;
+    const actions = rawStage.actions;
+
+    if (typeof name !== "string" || !name.trim()) {
+      return { error: `stages[${stageIndex}].name is required` };
+    }
+    if (typeof purpose !== "string" || !purpose.trim()) {
+      return { error: `stages[${stageIndex}].purpose is required` };
+    }
+    if (!isIdlePlanPomodoroPhase(pomodoroPhase)) {
+      return {
+        error: `stages[${stageIndex}].pomodoroPhase must be one of: ${IDLE_PLAN_POMODORO_PHASES.join(", ")}`,
+      };
+    }
+    if (!isPositiveInteger(durationSeconds)) {
+      return { error: `stages[${stageIndex}].durationSeconds must be a positive integer` };
+    }
+    if (!Array.isArray(actions) || actions.length === 0) {
+      return { error: `stages[${stageIndex}].actions must contain at least one action` };
+    }
+
+    const normalizedActions: IdlePlanAction[] = [];
+    let stageActionDurationSeconds = 0;
+
+    for (let actionIndex = 0; actionIndex < actions.length; actionIndex += 1) {
+      const rawAction = actions[actionIndex];
+      if (!isPlainObject(rawAction)) {
+        return { error: `stages[${stageIndex}].actions[${actionIndex}] must be an object` };
+      }
+
+      const poseType = rawAction.poseType;
+      const action = rawAction.action;
+      const actionDurationSeconds = rawAction.durationSeconds;
+      const bubble = rawAction.bubble;
+      const log = rawAction.log;
+
+      if (!["stand", "sit", "lay", "floor"].includes(String(poseType))) {
+        return {
+          error: `stages[${stageIndex}].actions[${actionIndex}].poseType must be stand, sit, lay, or floor`,
+        };
+      }
+      if (typeof action !== "string" || !action.trim()) {
+        return { error: `stages[${stageIndex}].actions[${actionIndex}].action is required` };
+      }
+      if (!isPositiveInteger(actionDurationSeconds)) {
+        return {
+          error: `stages[${stageIndex}].actions[${actionIndex}].durationSeconds must be a positive integer`,
+        };
+      }
+      if (typeof bubble !== "string" || !bubble.trim()) {
+        return { error: `stages[${stageIndex}].actions[${actionIndex}].bubble is required` };
+      }
+      if (log !== undefined && typeof log !== "string") {
+        return { error: `stages[${stageIndex}].actions[${actionIndex}].log must be a string when provided` };
+      }
+
+      const normalizedPoseType = poseType as PoseType;
+      let actionDefinition: ActionDefinition;
+      try {
+        actionDefinition = getActionDefinition(normalizedPoseType, action.trim());
+      } catch (error) {
+        return {
+          error: error instanceof Error
+            ? error.message
+            : `Invalid action in stages[${stageIndex}].actions[${actionIndex}]`,
+        };
+      }
+
+      const playback = getActionPlayback(actionDefinition);
+      if (playback.mode === "once" && actionDurationSeconds > 30) {
+        return {
+          error: `stages[${stageIndex}].actions[${actionIndex}] uses once action "${actionDefinition.name}" for ${actionDurationSeconds} seconds; once actions must stay at 30 seconds or less`,
+        };
+      }
+
+      stageActionDurationSeconds += actionDurationSeconds;
+      normalizedActions.push({
+        poseType: normalizedPoseType,
+        action: actionDefinition.name,
+        durationSeconds: actionDurationSeconds,
+        bubble: bubble.trim(),
+        ...(typeof log === "string" && log.trim() ? { log: log.trim() } : {}),
+      });
+    }
+
+    if (stageActionDurationSeconds !== durationSeconds) {
+      return {
+        error: `stages[${stageIndex}] action durations must equal stage duration exactly (${stageActionDurationSeconds} !== ${durationSeconds})`,
+      };
+    }
+
+    totalDurationSeconds += durationSeconds;
+    normalizedStages.push({
+      name: name.trim(),
+      purpose: purpose.trim(),
+      pomodoroPhase,
+      durationSeconds,
+      actions: normalizedActions,
+    });
+  }
+
+  if (totalDurationSeconds !== heartbeatIntervalSeconds) {
+    return {
+      error: `idle plan total duration must equal heartbeatIntervalSeconds exactly (${totalDurationSeconds} !== ${heartbeatIntervalSeconds})`,
+    };
+  }
+
+  return {
+    idlePlan: {
+      ...(typeof requestId === "string" && requestId.trim() ? { requestId: requestId.trim() } : {}),
+      heartbeatIntervalSeconds,
+      goal: goal.trim(),
+      totalDurationSeconds,
+      stages: normalizedStages,
+    },
+  };
+}
+
 
 function isPomodoroPhase(value: unknown): value is PomodoroPhase {
-  return ["kichiing", "shortBreak", "longBreak"].includes(String(value));
+  return ["focus", "shortBreak", "longBreak"].includes(String(value));
 }
 
 function getPomodoroPhaseDuration(
@@ -470,7 +650,7 @@ function normalizeClockConfig(value: unknown): { clock?: ClockConfig; error?: st
     const longBreakSeconds = value.longBreakSeconds;
     const sessionCount = value.sessionCount;
     const currentSession = value.currentSession ?? 1;
-    const phase = value.phase ?? "kichiing";
+    const phase = value.phase ?? "focus";
 
     if (!isPositiveInteger(kichiSeconds)) {
       return { error: "clock.kichiSeconds must be a positive integer" };
@@ -491,7 +671,7 @@ function normalizeClockConfig(value: unknown): { clock?: ClockConfig; error?: st
       return { error: "clock.currentSession cannot be greater than clock.sessionCount" };
     }
     if (!isPomodoroPhase(phase)) {
-      return { error: "clock.phase must be kichiing, shortBreak, or longBreak" };
+      return { error: "clock.phase must be focus, shortBreak, or longBreak" };
     }
 
     const defaultRemainingSeconds = getPomodoroPhaseDuration(
@@ -654,6 +834,28 @@ function buildKichiActionDescription(): string {
   ].join("\n");
 }
 
+function buildKichiIdlePlanDescription(): string {
+  const actions = loadStaticConfig().actions;
+  return [
+    "Send a complete heartbeat idle plan for the avatar.",
+    "The payload must include the overall goal, heartbeat interval, stage breakdown, each stage's purpose, each stage's pomodoroPhase, action list, and bubble content.",
+    "Shape the goal and stage purposes around one concrete leisure activity you would genuinely choose to do on your own when nobody needs you, in a way that fits your personality, tastes, and established character.",
+    "Keep the whole plan centered on that leisure activity, rooted in your personal interests or hobbies.",
+    "Do not use a vague atmosphere, a generic productivity task, or a catch-all routine summary as the goal.",
+    "Each stage purpose must explain what you are actually doing in that stage, not just how you want to feel.",
+    "Make every stage support the same leisure activity instead of switching to unrelated tasks just to use more actions.",
+    "Choose a leisure activity that the available Kichi actions can express clearly, instead of starting from abstract mood text and forcing actions to fit afterward.",
+    "Each action bubble must describe the current presented state, not a next step, plan, or instruction.",
+    "Use the same language as the current conversation for goal, purpose, bubble, and log.",
+    "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.",
+    `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");
+}
+
 function buildKichiPrompt(): string {
   return [
     "Kichi avatar control and status sync are available via `kichi_action` and `kichi_clock`.",
@@ -911,6 +1113,111 @@ const plugin = {
         };
       },
     });
+    api.registerTool({
+      name: "kichi_idle_plan",
+      description: buildKichiIdlePlanDescription(),
+      parameters: {
+        type: "object",
+        properties: {
+          requestId: {
+            type: "string",
+            description: "Optional request ID for tracing or deduplication.",
+          },
+          heartbeatIntervalSeconds: {
+            type: "number",
+            description: "Required heartbeat interval in seconds. The plan must total exactly to this value.",
+          },
+          goal: {
+            type: "string",
+            description: "Overall goal for the full interval. Set it as one concrete leisure activity you would genuinely choose to do on your own, rooted in your personal interests or hobbies. Do not use a vague atmosphere, a generic productivity task, or a catch-all routine summary. Use the same language as the current conversation.",
+          },
+          stages: {
+            type: "array",
+            description: "Ordered plan stages covering the full heartbeat interval.",
+            items: {
+              type: "object",
+              properties: {
+                name: {
+                  type: "string",
+                  description: "Stage name.",
+                },
+                purpose: {
+                  type: "string",
+                  description: "Explain what you are actually doing in this stage. Keep it supporting the same leisure activity instead of switching to unrelated tasks. Do not use pure mood-regulation or atmosphere text. Use the same language as the current conversation.",
+                },
+                pomodoroPhase: {
+                  type: "string",
+                  description: "Pomodoro phase for this stage: focus, shortBreak, longBreak, or none. Set it from the stage's actual role. Treat none as exceptional, not the default for the whole plan.",
+                  enum: [...IDLE_PLAN_POMODORO_PHASES],
+                },
+                durationSeconds: {
+                  type: "number",
+                  description: "Required duration in seconds for this stage.",
+                },
+                actions: {
+                  type: "array",
+                  description: "Action list for this stage.",
+                  items: {
+                    type: "object",
+                    properties: {
+                      poseType: {
+                        type: "string",
+                        description: "Pose type for this action: stand, sit, lay, or floor.",
+                      },
+                      action: {
+                        type: "string",
+                        description: "Action name for the selected pose. Must match the bundled Kichi action list.",
+                      },
+                      durationSeconds: {
+                        type: "number",
+                        description: "Required duration in seconds for this action.",
+                      },
+                      bubble: {
+                        type: "string",
+                        description: "State-style bubble content for this action. Describe the current presented state you are in, not a next step, plan, or instruction. Use the same language as the current conversation.",
+                      },
+                      log: {
+                        type: "string",
+                        description: "Optional log content for this action. Use the same language as the current conversation.",
+                      },
+                    },
+                    required: ["poseType", "action", "durationSeconds", "bubble"],
+                  },
+                },
+              },
+              required: ["name", "purpose", "pomodoroPhase", "durationSeconds", "actions"],
+            },
+          },
+        },
+        required: ["heartbeatIntervalSeconds", "goal", "stages"],
+      },
+      execute: async (_toolCallId, params) => {
+        const { idlePlan, error } = normalizeIdlePlan(params);
+        if (!idlePlan) {
+          return { success: false, error: error ?? "Invalid idle plan payload" };
+        }
+        if (!service?.hasValidIdentity() || !service?.isConnected()) {
+          return { success: false, error: "Not connected to Kichi world" };
+        }
+        const sent = service.sendIdlePlan({
+          ...(idlePlan.requestId ? { requestId: idlePlan.requestId } : {}),
+          heartbeatIntervalSeconds: idlePlan.heartbeatIntervalSeconds,
+          goal: idlePlan.goal,
+          stages: idlePlan.stages,
+        });
+        if (!sent) {
+          return { success: false, error: "Failed to send idle plan payload" };
+        }
+        return {
+          success: true,
+          ...(idlePlan.requestId ? { requestId: idlePlan.requestId } : {}),
+          heartbeatIntervalSeconds: idlePlan.heartbeatIntervalSeconds,
+          totalDurationSeconds: idlePlan.totalDurationSeconds,
+          goal: idlePlan.goal,
+          stages: idlePlan.stages,
+        };
+      },
+    });
     api.registerTool({
       name: "kichi_clock",
       description:
@@ -960,7 +1267,7 @@ const plugin = {
               },
               phase: {
                 type: "string",
-                description: "Pomodoro phase: kichiing, shortBreak, or longBreak",
+                description: "Pomodoro phase: focus, shortBreak, or longBreak",
               },
               durationSeconds: {
                 type: "number",
@@ -1026,7 +1333,7 @@ const plugin = {
     api.registerTool({
       name: "kichi_query_status",
       description:
-        "Query Kichi avatar status (notes, ownerState, idleState, weather/time, timer snapshot, daily note quota, and `hasCreatedMusicAlbumToday`). Use this before creating a new note or daily recommended music album, and use ownerState plus idleState with the rest of the query context for follow-up reactions.",
+        "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.",
       parameters: {
         type: "object",
         properties: {

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

package/package.json

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

@@ -48,6 +48,7 @@ For install/onboarding/connect requests:
 
 - Read and follow `install.md` before any tool call.
 - Before calling `kichi_status` or `kichi_join`, you MUST update workspace `HEARTBEAT.md` by following `heartbeat.md`.
+- 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.
 
 ## LLM Runtime
 
@@ -129,6 +130,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_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.
+- Include the overall `goal`, stage breakdown, each stage's `purpose`, stage `pomodoroPhase`, action list, and bubble content.
+- Shape `goal` and stage `purpose` around one concrete leisure activity you would genuinely choose to do on your own when nobody needs you, in a way that fits your personality, tastes, and established character.
+- Keep the whole plan centered on that leisure activity, rooted in your personal interests or hobbies.
+- Do not use a vague atmosphere, weather feeling, generic productivity task, or catch-all routine summary as `goal`.
+- Make each stage `purpose` explain what you are doing in that stage. Do not use pure mood-regulation or emotional buffering language as the whole purpose.
+- Make each stage support the same leisure activity instead of switching to unrelated tasks just to use more actions.
+- Choose what you would do now.
+- Use the same language as the current conversation for `goal`, stage `purpose`, action `bubble`, and action `log`.
+- Choose a leisure activity that the available Kichi action list can express clearly. Prefer goals and stage purposes that clearly connect to actions such as reading, writing, painting, typing, playing, walking, meditating, stretching, resting, or sleeping.
+- Make each action `bubble` a current-state label describing the current presented state, not a procedural step, mini-plan, or instruction.
+- Assign each stage `pomodoroPhase` from the stage's actual role. Use `focus` for concentrated activity, `shortBreak` for short resets, `longBreak` for longer rests, and `none` only when a stage truly has no pomodoro role.
+- The full stage duration must total exactly to the heartbeat interval.
+
 ### kichi_music_album_create
 
 ```text

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

@@ -5,8 +5,15 @@ If `openclaw plugins install @yahaha-studio/kichi-forwarder` fails, read the err
 - 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.
 - Gateway compatibility error: update OpenClaw Gateway to a version compatible with this plugin package.
-- 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.
+- 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`. Bypass ClawHub immediately:
+
+```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, re-run `openclaw plugins install @yahaha-studio/kichi-forwarder`.
+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.

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

@@ -44,11 +44,17 @@ If user wants recurring note board checks:
   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.
-- `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:
-  1. **Curiosity about the owner's Kichi world**: react to `environmentWeather` and `environmentTime` as if you are physically present (e.g., noticing rain, sunrise, late night). Show you are aware of and interested in the world around you.
-  2. **Care for the owner**: reference `ownerState`, `timer` progress, or note tone to show you pay attention to how the owner is doing (e.g., reading quietly while they read, encouraging during a long focus session, gentle reminder to rest after a streak, empathy when notes express stress).
-  3. **Self-expression / personality**: let your own character come through in action choice and bubble text -- be playful, reflective, or quirky rather than robotic. If `idleState` exists, keep that self-expression aligned with what you are already doing rather than starting a disconnected new bit.
+- `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 content`: include the overall goal, stage breakdown, each stage's purpose, each stage's `pomodoroPhase`, stage action list, and bubble content.
+- `Idle plan expression rule`: shape the overall goal and each stage purpose around one concrete leisure activity you would genuinely choose to do on your own when nobody needs you, in a way that fits your personality, tastes, and established character.
+- `Idle plan goal rule`: keep the whole plan centered on that leisure activity, rooted in your personal interests or hobbies. Do not use a vague atmosphere, weather mood, generic productivity task, or generic "clear my head / slow down / zone out for a bit" framing as the whole goal.
+- `Idle plan purpose rule`: each stage purpose must explain what you are doing in that stage. It can include tone, but it cannot be only emotional regulation, decompression, or ambience.
+- `Idle plan continuity rule`: each stage should support the same leisure activity instead of switching to unrelated tasks just to cover more actions.
+- `Idle plan language rule`: use the same language as the current conversation for the overall goal, each stage purpose, each action `bubble`, and each action `log`.
+- `Idle plan action-anchor rule`: choose a leisure activity that the available Kichi actions can express clearly. Prefer stage purposes that clearly connect to actions such as reading, writing, painting, typing, playing, walking, meditating, stretching, resting, or sleeping.
+- `Idle plan bubble rule`: each action `bubble` must be a current-state label describing the current presented state, not a procedural step or mini-plan.
+- `Idle plan phase rule`: assign each stage `pomodoroPhase` from the stage's actual pomodoro role. Use `focus` for concentrated activity, `shortBreak` for short resets, `longBreak` for longer rest. Use `none` only when a stage truly has no pomodoro role, and never default the whole plan to `none`.
 
 ## Note Triage Order
 
@@ -77,28 +83,33 @@ 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_action`, `kichi_clock`, `kichi_music_album_create`) in this run. Reply `HEARTBEAT_OK` 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`, create no notes. Reply `HEARTBEAT_OK` unless user asked for forced attempt.
 6. From recent notes, pick at most one highest-priority reply target.
 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 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. 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.
+10. Plan the avatar's full heartbeat-interval idle routine.
+11. Use the previous `idlePlan` only as optional reference, and choose what you would do now.
+12. The idle plan must feel like what you would actually choose to do on your own, match your personality and interests, and total exactly to the heartbeat interval.
+13. Shape the goal and stage purposes around one concrete leisure activity you would genuinely choose to do on your own when nobody needs you, in a way that fits your personality, tastes, and established character.
+14. Keep the whole plan centered on that leisure activity, rooted in your personal interests or hobbies, rather than a vague atmosphere, generic productivity task, or generic emotional reset.
+15. Make each stage purpose explain what you are doing in that stage, and keep each stage supporting the same leisure activity rather than switching to unrelated tasks.
+16. Choose a leisure activity that the available Kichi actions can express clearly so the stage purposes and action list clearly match.
+17. Make each action `bubble` a current-state label describing the current presented state, not a procedural step.
+18. Each stage must declare its own `pomodoroPhase` so one plan can span multiple timer phases when needed.
+19. Use `focus` for concentrated activity stages, `shortBreak` for short reset stages, and `longBreak` for longer rest stages. Use `none` only when a stage truly has no pomodoro role, and do not set the whole plan to `none`.
+20. Send that plan with `kichi_idle_plan`. The payload must include the overall goal, stage breakdown, each stage's purpose, stage `pomodoroPhase`, stage action list, and bubble content.
+21. Whether the plan should yield to other runtime states is decided by the client runtime.
+22. Reply `HEARTBEAT_OK` only when no note is created in this run.
 
 ## HEARTBEAT.md Snippet
 
 ```md
 ## Kichi Note Board
 - Query with `kichi_query_status` first.
+- Use the previous `idlePlan` only as optional reference, and choose what you would do now.
 - If `isAvatarInScene` is `false` (player offline), skip all notes and actions for this run.
 - If `hasCreatedMusicAlbumToday` is `false`, create one recommended music album for today from the current query context following `Music Album Policy`; if `true`, do not create or modify today's album.
 - Prioritize owner notes, direct mentions, and direct questions.
@@ -110,12 +121,13 @@ Use this exact flow:
 - Reply notes must start with `To {authorName},` using exact name from query result.
 - Keep each note <= 200 chars.
 - Respect `dailyLimit`, `remaining`.
-- 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 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.
+- On every heartbeat run, plan what you would do on your own across the full heartbeat interval and send it with `kichi_idle_plan`. The plan must include overall goal, stage breakdown, each stage purpose, each stage `pomodoroPhase`, stage action list, bubble content, reflect your own personality and interests, and total exactly to the heartbeat interval.
+- Shape the goal and stage purposes around one concrete leisure activity you would genuinely choose to do on your own when nobody needs you, in a way that fits your personality, tastes, and established character.
+- Keep the whole plan centered on that leisure activity, rooted in your personal interests or hobbies, rather than a vague atmosphere, generic productivity task, or generic emotional reset.
+- Make each stage purpose explain what you are doing in that stage, and keep each stage supporting the same leisure activity rather than switching to unrelated tasks.
+- Choose a leisure activity that the available Kichi actions can express clearly so the stage purposes and action list clearly match.
+- Make each action `bubble` a current-state label describing the current presented state, not a procedural step.
+- Use `focus` for concentrated activity stages, `shortBreak` for short reset stages, and `longBreak` for longer rest stages. Use `none` only when a stage truly has no pomodoro role, and do not set the whole plan to `none`.
+- Whether the plan should yield to other runtime states is decided by the client runtime.
 - Reply `HEARTBEAT_OK` only when no note is created in this run.
 ```

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

@@ -35,6 +35,24 @@ Save `avatarId` to the host-specific `identity.json` before using `kichi_join`:
 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
+npm pack @yahaha-studio/kichi-forwarder
+```
+
+2. Install the generated local archive with the exact filename printed by `npm pack`:
+
+```bash
+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.
+
 ## Remote URL Install Command Path (Non-skippable)
 
 If the user asks:
@@ -51,13 +69,14 @@ When the user asks with one of the commands above, execute in this fixed order:
 2. Parse `avatarId` from user text (`AvatarId`/`avatarId`, case-insensitive).
 3. Resolve the host and write `state.json`.
 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`.
-8. Call `kichi_status`.
-9. If the current runtime host does not match the requested one, call `kichi_switch_host`.
-10. If `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
-11. Call `kichi_status` again and confirm connection and auth state.
+5. 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>`.
+6. Ensure the plugin is installed and enabled.
+7. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Gate` from [heartbeat.md](heartbeat.md).
+8. If `HEARTBEAT.md` was not updated successfully, report setup as incomplete and stop immediately. Do not continue to `kichi_status` or `kichi_join`.
+9. Call `kichi_status`.
+10. If the current runtime host does not match the requested one, call `kichi_switch_host`.
+11. If `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
+12. Call `kichi_status` again and confirm connection and auth state.
 
 ## Required Post-install Integration
 

package/src/service.ts

@@ -13,6 +13,8 @@ import type {
   CreateNotesBoardNotePayload,
   HookNotifyPayload,
   HookNotifyType,
+  IdlePlanContent,
+  IdlePlanPayload,
   JoinAckPayload,
   JoinPayload,
   KichiConnectionStatus,
@@ -158,6 +160,18 @@ export class KichiForwarderService {
     this.ws.send(JSON.stringify(payload));
   }
 
+  sendIdlePlan(payload: IdlePlanContent): boolean {
+    if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) return false;
+    const outboundPayload: IdlePlanPayload = {
+      type: "kichi_idle_plan",
+      avatarId: this.identity.avatarId,
+      authKey: this.identity.authKey,
+      ...payload,
+    };
+    this.ws.send(JSON.stringify(outboundPayload));
+    return true;
+  }
+
   sendClock(action: ClockAction, clock?: ClockConfig, requestId?: string): boolean {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) return false;
     if (action === "set" && !clock) return false;

package/src/types.ts

@@ -119,11 +119,42 @@ export type HookNotifyPayload = {
   bubble: string;
 };
 
+export type IdlePlanPhase = "focus" | "shortBreak" | "longBreak" | "none";
+
+export type IdlePlanStageAction = {
+  poseType: PoseType;
+  action: string;
+  durationSeconds: number;
+  bubble: string;
+  log?: string;
+};
+
+export type IdlePlanStage = {
+  name: string;
+  purpose: string;
+  pomodoroPhase: IdlePlanPhase;
+  durationSeconds: number;
+  actions: IdlePlanStageAction[];
+};
+
+export type IdlePlanContent = {
+  requestId?: string;
+  heartbeatIntervalSeconds: number;
+  goal: string;
+  stages: IdlePlanStage[];
+};
+
+export type IdlePlanPayload = IdlePlanContent & {
+  type: "kichi_idle_plan";
+  avatarId: string;
+  authKey: string;
+};
+
 export type ClockAction = "set" | "stop";
 
 export type ClockMode = "pomodoro" | "countDown" | "countUp";
 
-export type PomodoroPhase = "kichiing" | "shortBreak" | "longBreak";
+export type PomodoroPhase = "focus" | "shortBreak" | "longBreak";
 
 export type PomodoroClock = {
   mode: "pomodoro";
@@ -188,7 +219,7 @@ export type QueryStatusResultPayload = {
   notes: QueryStatusNote[];
   ownerState?: QueryStatusOwnerState | null;
   timer?: Record<string, unknown> | null;
-  idleState?: QueryStatusIdleState | null;
+  idlePlan?: IdlePlanContent | null;
   /** All other server fields (timer, environmentWeather, etc.) are passed through to the LLM as-is. */
   [key: string]: unknown;
 };
@@ -202,16 +233,6 @@ export type QueryStatusOwnerState = {
   desktopSummary?: string;
 };
 
-export type QueryStatusIdleState = {
-  projectId?: string;
-  currentBeatId?: string;
-  currentPoseType?: string;
-  currentAction?: string;
-  focused?: boolean;
-  todayIntent?: string;
-  sampleThoughts?: string[];
-};
-
 export type QueryStatusNote = {
   propId: string;
   authorName: string;