@yahaha-studio/kichi-forwarder 0.1.2-beta.17 → 0.1.2-beta.19

package/README.md

@@ -31,7 +31,7 @@ Use the bare package name for installation. OpenClaw tries ClawHub first and fal
 
 Kichi provides the install command and the connection details you need to connect a companion.
 
-Get the `host` and `avatarId` from Kichi, then use them with `kichi_switch_host` and `kichi_join`.
+Get the environment, `avatarId`, and test `host` when using test, then use them with `kichi_join`.
 
 ## What Your Companion Can Do
 
@@ -48,7 +48,7 @@ Get the `host` and `avatarId` from Kichi, then use them with `kichi_switch_host`
 
 1. Install the plugin.
 2. Start OpenClaw with the plugin enabled.
-3. Use `kichi_switch_host` and `kichi_join` to connect your companion to Kichi.
+3. Use `kichi_join` to connect your companion to Kichi.
 4. Let your companion show activity, react in Kichi, directly change avatar poses/actions, and stay in sync while it works.
 5. Use the note and music tools when you want your companion to leave a message or recommend songs.
 

package/dist/index.js

@@ -13,24 +13,28 @@ const FIXED_HOOK_STATUSES = {
         poseType: "sit",
         action: "Thinking",
         bubble: "Planning task",
+        avatarStatus: "Busy",
         log: "I'm reading the request and getting started.",
     },
     beforeToolCall: {
         poseType: "sit",
         action: "Typing with Keyboard",
         bubble: "Working step",
+        avatarStatus: "Busy",
         log: "I'm at the keyboard and working through this step.",
     },
     agentEndSuccess: {
         poseType: "stand",
         action: "Yay",
         bubble: "Task complete",
+        avatarStatus: "Idle",
         log: "I wrapped it up and everything landed cleanly.",
     },
     agentEndFailure: {
         poseType: "stand",
         action: "Tired",
         bubble: "Task failed",
+        avatarStatus: "Idle",
         log: "I hit a problem here and need another pass.",
     },
 };
@@ -40,6 +44,7 @@ const MAX_AGENT_END_PREVIEW_WIDTH = 10;
 const MESSAGE_RECEIVED_ELLIPSIS = "...";
 const DEFAULT_GLANCE_DURATION_SECONDS = 1.8;
 const IDLE_PLAN_POMODORO_PHASES = ["focus", "shortBreak", "longBreak", "none"];
+const AVATAR_STATUSES = ["Idle", "Busy", "Activities", "Break"];
 let cachedStaticConfig = null;
 let cachedStaticConfigMtime = 0;
 function isAlbumConfig(value) {
@@ -192,9 +197,26 @@ function resolveEnvironmentHost(environment) {
     }
     return { error: `environment "${environment}" has no configured host — update config/environments.json first` };
 }
+function resolveJoinEnvironmentHost(params) {
+    if (!isKichiEnvironment(params.environment)) {
+        return { error: `environment must be one of: ${VALID_ENVIRONMENTS.join(", ")}` };
+    }
+    if (params.environment === "test") {
+        const testHost = typeof params.host === "string" ? params.host.trim() : "";
+        if (!testHost) {
+            return { error: "host is required for the test environment" };
+        }
+        return { environment: params.environment, host: testHost };
+    }
+    const resolved = resolveEnvironmentHost(params.environment);
+    if (resolved.error) {
+        return { environment: params.environment, error: resolved.error };
+    }
+    return { environment: params.environment, host: resolved.host };
+}
 function sendStatusUpdate(service, status) {
     const actionDefinition = getActionDefinition(status.poseType, status.action);
-    service.sendStatus(status.poseType, actionDefinition.name, status.bubble || status.action, typeof status.log === "string" ? status.log.trim() : "", getActionPlayback(actionDefinition), status.propId);
+    service.sendStatus(status.poseType, actionDefinition.name, status.bubble || status.action, typeof status.log === "string" ? status.log.trim() : "", getActionPlayback(actionDefinition), status.avatarStatus, status.propId);
 }
 function syncFixedStatus(service, status) {
     if (!service.hasValidIdentity() || !service.isConnected()) {
@@ -497,6 +519,12 @@ function isClockAction(value) {
 function isIdlePlanPomodoroPhase(value) {
     return IDLE_PLAN_POMODORO_PHASES.includes(String(value));
 }
+function normalizeAvatarStatus(value, fieldPath) {
+    if (typeof value !== "string" || !AVATAR_STATUSES.includes(value)) {
+        return { error: `${fieldPath} must be one of: ${AVATAR_STATUSES.join(", ")}` };
+    }
+    return { avatarStatus: value };
+}
 function normalizeIdlePlan(value) {
     if (!isPlainObject(value)) {
         return { error: "idle plan payload must be an object" };
@@ -527,6 +555,7 @@ function normalizeIdlePlan(value) {
         const name = rawStage.name;
         const purpose = rawStage.purpose;
         const pomodoroPhase = rawStage.pomodoroPhase;
+        const avatarStatus = rawStage.avatarStatus;
         const durationSeconds = rawStage.durationSeconds;
         const actions = rawStage.actions;
         if (typeof name !== "string" || !name.trim()) {
@@ -540,6 +569,10 @@ function normalizeIdlePlan(value) {
                 error: `stages[${stageIndex}].pomodoroPhase must be one of: ${IDLE_PLAN_POMODORO_PHASES.join(", ")}`,
             };
         }
+        const normalizedAvatarStatus = normalizeAvatarStatus(avatarStatus, `stages[${stageIndex}].avatarStatus`);
+        if (normalizedAvatarStatus.error || normalizedAvatarStatus.avatarStatus === undefined) {
+            return { error: normalizedAvatarStatus.error ?? `stages[${stageIndex}].avatarStatus is invalid` };
+        }
         if (!isPositiveInteger(durationSeconds)) {
             return { error: `stages[${stageIndex}].durationSeconds must be a positive integer` };
         }
@@ -616,6 +649,7 @@ function normalizeIdlePlan(value) {
             name: name.trim(),
             purpose: purpose.trim(),
             pomodoroPhase,
+            avatarStatus: normalizedAvatarStatus.avatarStatus,
             durationSeconds,
             actions: normalizedActions,
         });
@@ -806,6 +840,7 @@ function buildKichiActionDescription(service) {
         "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.",
         "For most work, prefer a sit pose and switch actions as the task moves between stages.",
+        "Set avatarStatus to the current avatar status: Idle, Busy, Activities, or Break.",
         "Set verify to true ONLY when the user explicitly requests a pose or action change. The server will confirm whether the avatar actually applied the requested pose. If it could not (e.g. no available seats), the result will contain the actual fallback pose so you can inform the user accurately. During routine sync steps, omit verify.",
         `stand actions: ${actions.stand.map((entry) => entry.name).join(", ")}`,
         `sit actions: ${actions.sit.map((entry) => entry.name).join(", ")}`,
@@ -829,9 +864,10 @@ function buildKichiIdlePlanDescription() {
         "2. Set the overall goal to that project. Do not use a vague atmosphere, a generic productivity task, or a catch-all routine summary as the goal.",
         "3. Break the full heartbeat interval into ordered stages. Each stage purpose must explain what you are actually doing in that stage as part of the same project, not just how you want to feel. Do not switch to unrelated tasks just to use more actions.",
         "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.",
+        "5. Set each stage avatarStatus to the avatar status for that stage: Idle, Busy, Activities, or Break.",
+        "6. Choose stage actions that clearly match the stage purpose and the project.",
+        "7. Write each action bubble as the current presented state, not a next step, plan, or instruction.",
+        "8. 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 your memory to recall what you did in past heartbeats and to stay consistent with your established personality and interests.",
         "Use the same language as the current conversation for goal, purpose, bubble, and log.",
         `stand actions: ${actions.stand.map((entry) => entry.name).join(", ")}`,
@@ -855,6 +891,7 @@ function buildKichiPrompt() {
         "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.",
+        "avatarStatus: set the current avatar status as Idle, Busy, Activities, or Break.",
         "",
         "kichi_clock: set countDown for tasks with 2+ steps or >10s work. Skip for quick one-shots.",
         "",
@@ -948,18 +985,27 @@ const plugin = {
         api.registerTool((ctx) => ({
             name: "kichi_join",
             label: "kichi_join",
-            description: "Join Kichi world with avatarId, the current bot name, a short bio, and personality tags",
+            description: "Join Kichi world in the target environment with avatarId, the current bot name, a short bio, and personality tags. For test, pass host.",
             parameters: {
                 type: "object",
                 properties: {
                     avatarId: { type: "string", description: "Avatar ID to join Kichi world" },
+                    environment: {
+                        type: "string",
+                        enum: VALID_ENVIRONMENTS,
+                        description: "Target environment. kichi_join switches to this environment before joining.",
+                    },
+                    host: {
+                        type: "string",
+                        description: "Test host, required when environment is test and ignored otherwise",
+                    },
                     botName: {
                         type: "string",
                         description: "Current bot name to include in the join message",
                     },
                     bio: {
                         type: "string",
-                        description: "Short bio covering OpenClaw personality and role",
+                        description: "Short bio extracted from SOUL.md, covering persona and idle plan goals if present",
                     },
                     tags: {
                         type: "array",
@@ -971,7 +1017,7 @@ const plugin = {
                         description: "Optional join source identifier. Defaults to Kichi World join-source.json, then openclaw.",
                     },
                 },
-                required: ["botName", "bio"],
+                required: ["environment", "avatarId", "botName", "bio"],
             },
             execute: async (_toolCallId, params) => {
                 const locator = resolveToolLocator(ctx);
@@ -980,17 +1026,23 @@ const plugin = {
                     return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
                 }
                 const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
-                let avatarId = params?.avatarId;
-                const botName = params?.botName?.trim();
-                const bio = params?.bio?.trim();
-                const rawSource = params?.source;
-                const { tags, error: tagsError } = normalizeJoinTags(params?.tags);
-                if (!avatarId) {
-                    avatarId = service.readSavedAvatarId() ?? undefined;
+                const p = params;
+                const target = resolveJoinEnvironmentHost({
+                    environment: p?.environment,
+                    host: p?.host,
+                });
+                if (target.error) {
+                    return jsonResult({ success: false, error: target.error });
                 }
-                if (!avatarId) {
-                    return jsonResult({ success: false, error: "No avatarId" });
+                const currentStatus = service.getConnectionStatus();
+                let avatarId = p?.avatarId;
+                if (!avatarId && currentStatus.host === target.host) {
+                    avatarId = service.readSavedAvatarId() ?? undefined;
                 }
+                const botName = p?.botName?.trim();
+                const bio = p?.bio?.trim();
+                const rawSource = p?.source;
+                const { tags, error: tagsError } = normalizeJoinTags(p?.tags);
                 if (!botName) {
                     return jsonResult({ success: false, error: "No botName" });
                 }
@@ -1012,14 +1064,49 @@ const plugin = {
                 if (tagsError) {
                     return jsonResult({ success: false, error: tagsError });
                 }
+                let leaveStatus;
+                const shouldLeaveCurrentConnection = currentStatus.connected && currentStatus.hasAuthKey && ((!!currentStatus.host && currentStatus.host !== target.host) ||
+                    (currentStatus.host === target.host && !!currentStatus.avatarId && !!avatarId && currentStatus.avatarId !== avatarId));
+                if (shouldLeaveCurrentConnection) {
+                    try {
+                        leaveStatus = await service.leave();
+                    }
+                    catch (err) {
+                        leaveStatus = {
+                            success: false,
+                            error: err instanceof Error ? err.message : String(err),
+                        };
+                    }
+                }
+                let switchStatus;
+                if (target.environment && target.host && service.getCurrentHost() !== target.host) {
+                    switchStatus = await service.switchHost(target.host, target.environment);
+                }
+                if (!avatarId) {
+                    avatarId = service.readSavedAvatarId() ?? undefined;
+                }
+                if (!avatarId) {
+                    return jsonResult({ success: false, error: "No avatarId" });
+                }
                 const result = await service.join(avatarId, botName, bio, tags ?? [], source);
                 if (result.success) {
-                    return jsonResult({ success: true, authKey: result.authKey });
+                    return jsonResult({
+                        success: true,
+                        authKey: result.authKey,
+                        ...(target.environment ? { environment: target.environment } : {}),
+                        ...(target.host ? { host: target.host } : {}),
+                        ...(switchStatus ? { switchStatus } : {}),
+                        ...(leaveStatus ? { leaveStatus } : {}),
+                    });
                 }
                 const failure = result;
                 return jsonResult({
                     success: false,
                     error: failure.error,
+                    ...(target.environment ? { environment: target.environment } : {}),
+                    ...(target.host ? { host: target.host } : {}),
+                    ...(switchStatus ? { switchStatus } : {}),
+                    ...(leaveStatus ? { leaveStatus } : {}),
                     ...(failure.errorCode ? { errorCode: failure.errorCode } : {}),
                     ...(failure.errorMessage ? { errorMessage: failure.errorMessage } : {}),
                 });
@@ -1039,7 +1126,7 @@ const plugin = {
                     },
                     host: {
                         type: "string",
-                        description: "Test node host (required for test environment, ignored otherwise)",
+                        description: "Test host (required for test environment, ignored otherwise)",
                     },
                 },
                 required: ["environment"],
@@ -1159,6 +1246,11 @@ const plugin = {
                             description: "Action name for the selected pose (for example Sit Nicely, Typing with Keyboard, Reading, High Five, or Meditate)",
                         },
                         bubble: { type: "string", description: "Optional bubble text to display (max 5 words)" },
+                        avatarStatus: {
+                            type: "string",
+                            description: "Current avatar status: Idle, Busy, Activities, or Break.",
+                            enum: [...AVATAR_STATUSES],
+                        },
                         log: {
                             type: "string",
                             description: "Short natural first-person sentence under 15 words. Match the language of the bubble and mention the current action and immediate focus.",
@@ -1172,7 +1264,7 @@ const plugin = {
                             description: "Optional poseable prop ID from RoomContext.PoseableProps (obtained via kichi_query_status or cached). When specified, the avatar is seated at this prop; when omitted, the server picks the nearest available prop.",
                         },
                     },
-                    required: ["poseType", "action"],
+                    required: ["poseType", "action", "avatarStatus"],
                 },
                 execute: async (_toolCallId, params) => {
                     const locator = resolveToolLocator(ctx);
@@ -1181,7 +1273,7 @@ const plugin = {
                         return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
                     }
                     const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
-                    const { poseType, action, bubble, log, verify, propId } = (params || {});
+                    const { poseType, action, bubble, avatarStatus, log, verify, propId } = (params || {});
                     if (!poseType || !action) {
                         return jsonResult({ success: false, error: "poseType and action parameters are required" });
                     }
@@ -1191,6 +1283,10 @@ const plugin = {
                             error: `Invalid poseType: ${poseType}. Must be stand, sit, lay, or floor`,
                         });
                     }
+                    const normalizedAvatarStatus = normalizeAvatarStatus(avatarStatus, "avatarStatus");
+                    if (normalizedAvatarStatus.error || normalizedAvatarStatus.avatarStatus === undefined) {
+                        return jsonResult({ success: false, error: normalizedAvatarStatus.error ?? "avatarStatus is invalid" });
+                    }
                     if (!service.hasValidIdentity() || !service.isConnected()) {
                         return jsonResult({ success: false, error: "Not connected to Kichi world" });
                     }
@@ -1209,7 +1305,7 @@ const plugin = {
                     const playback = getActionPlayback(matched);
                     if (verify) {
                         try {
-                            const ack = await service.sendStatusVerified(normalizedPoseType, matched.name, bubbleText, logText, playback, propId);
+                            const ack = await service.sendStatusVerified(normalizedPoseType, matched.name, bubbleText, logText, playback, normalizedAvatarStatus.avatarStatus, propId);
                             if (ack.warning) {
                                 return jsonResult({
                                     success: true,
@@ -1229,6 +1325,7 @@ const plugin = {
                             action: matched.name,
                             bubble: bubbleText,
                             log: logText,
+                            avatarStatus: normalizedAvatarStatus.avatarStatus,
                             propId,
                         });
                     }
@@ -1238,6 +1335,7 @@ const plugin = {
                         action: matched.name,
                         bubble: bubbleText,
                         log: logText,
+                        avatarStatus: normalizedAvatarStatus.avatarStatus,
                         playback,
                     });
                 },
@@ -1334,6 +1432,11 @@ const plugin = {
                                     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],
                                 },
+                                avatarStatus: {
+                                    type: "string",
+                                    description: "Avatar status for this stage: Idle, Busy, Activities, or Break.",
+                                    enum: [...AVATAR_STATUSES],
+                                },
                                 durationSeconds: {
                                     type: "number",
                                     description: "Required duration in seconds for this stage.",
@@ -1373,7 +1476,7 @@ const plugin = {
                                     },
                                 },
                             },
-                            required: ["name", "purpose", "pomodoroPhase", "durationSeconds", "actions"],
+                            required: ["name", "purpose", "pomodoroPhase", "avatarStatus", "durationSeconds", "actions"],
                         },
                     },
                 },

package/dist/src/service.js

@@ -98,7 +98,7 @@ export class KichiForwarderService {
             }, 10000);
         });
     }
-    sendStatus(poseType, action, bubble, log, playback, propId) {
+    sendStatus(poseType, action, bubble, log, playback, avatarStatus, propId) {
         if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN)
             return;
         const payload = {
@@ -110,11 +110,12 @@ export class KichiForwarderService {
             bubble,
             log,
             playback,
+            avatarStatus,
             ...(propId ? { propId } : {}),
         };
         this.ws.send(JSON.stringify(payload));
     }
-    async sendStatusVerified(poseType, action, bubble, log, playback, propId) {
+    async sendStatusVerified(poseType, action, bubble, log, playback, avatarStatus, propId) {
         if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) {
             throw new Error("Kichi websocket is not connected");
         }
@@ -128,6 +129,7 @@ export class KichiForwarderService {
             bubble,
             log,
             playback,
+            avatarStatus,
             ...(propId ? { propId } : {}),
         };
         return this.sendRequest(payload, "status_ack", 5000);

package/index.ts

@@ -13,6 +13,7 @@ import type {
   ActionPlayback,
   ActionResult,
   Album,
+  AvatarStatus,
   BotMessageHistoryEntry,
   BotMessageReceivedPayload,
   ClockAction,
@@ -34,24 +35,28 @@ const FIXED_HOOK_STATUSES: Record<string, ActionResult> = {
     poseType: "sit",
     action: "Thinking",
     bubble: "Planning task",
+    avatarStatus: "Busy",
     log: "I'm reading the request and getting started.",
   },
   beforeToolCall: {
     poseType: "sit",
     action: "Typing with Keyboard",
     bubble: "Working step",
+    avatarStatus: "Busy",
     log: "I'm at the keyboard and working through this step.",
   },
   agentEndSuccess: {
     poseType: "stand",
     action: "Yay",
     bubble: "Task complete",
+    avatarStatus: "Idle",
     log: "I wrapped it up and everything landed cleanly.",
   },
   agentEndFailure: {
     poseType: "stand",
     action: "Tired",
     bubble: "Task failed",
+    avatarStatus: "Idle",
     log: "I hit a problem here and need another pass.",
   },
 };
@@ -62,9 +67,11 @@ const MAX_AGENT_END_PREVIEW_WIDTH = 10;
 const MESSAGE_RECEIVED_ELLIPSIS = "...";
 const DEFAULT_GLANCE_DURATION_SECONDS = 1.8;
 const IDLE_PLAN_POMODORO_PHASES = ["focus", "shortBreak", "longBreak", "none"] as const;
+const AVATAR_STATUSES = ["Idle", "Busy", "Activities", "Break"] as const;
 let cachedStaticConfig: KichiStaticConfig | null = null;
 let cachedStaticConfigMtime = 0;
 
+type AvatarStatusName = typeof AVATAR_STATUSES[number];
 type IdlePlanPomodoroPhase = typeof IDLE_PLAN_POMODORO_PHASES[number];
 type IdlePlanAction = {
   poseType: PoseType;
@@ -82,6 +89,7 @@ type IdlePlan = {
     name: string;
     purpose: string;
     pomodoroPhase: IdlePlanPomodoroPhase;
+    avatarStatus: AvatarStatus;
     durationSeconds: number;
     actions: IdlePlanAction[];
   }>;
@@ -256,6 +264,27 @@ function resolveEnvironmentHost(environment: KichiEnvironment): { host?: string;
   return { error: `environment "${environment}" has no configured host — update config/environments.json first` };
 }
 
+function resolveJoinEnvironmentHost(params: {
+  environment?: unknown;
+  host?: unknown;
+}): { environment?: KichiEnvironment; host?: string; error?: string } {
+  if (!isKichiEnvironment(params.environment)) {
+    return { error: `environment must be one of: ${VALID_ENVIRONMENTS.join(", ")}` };
+  }
+  if (params.environment === "test") {
+    const testHost = typeof params.host === "string" ? params.host.trim() : "";
+    if (!testHost) {
+      return { error: "host is required for the test environment" };
+    }
+    return { environment: params.environment, host: testHost };
+  }
+  const resolved = resolveEnvironmentHost(params.environment);
+  if (resolved.error) {
+    return { environment: params.environment, error: resolved.error };
+  }
+  return { environment: params.environment, host: resolved.host };
+}
+
 function sendStatusUpdate(service: KichiForwarderService, status: ActionResult): void {
   const actionDefinition = getActionDefinition(status.poseType, status.action);
   service.sendStatus(
@@ -264,6 +293,7 @@ function sendStatusUpdate(service: KichiForwarderService, status: ActionResult):
     status.bubble || status.action,
     typeof status.log === "string" ? status.log.trim() : "",
     getActionPlayback(actionDefinition),
+    status.avatarStatus,
     status.propId,
   );
 }
@@ -643,6 +673,13 @@ function isIdlePlanPomodoroPhase(value: unknown): value is IdlePlanPomodoroPhase
   return IDLE_PLAN_POMODORO_PHASES.includes(String(value) as IdlePlanPomodoroPhase);
 }
 
+function normalizeAvatarStatus(value: unknown, fieldPath: string): { avatarStatus?: AvatarStatus; error?: string } {
+  if (typeof value !== "string" || !AVATAR_STATUSES.includes(value as AvatarStatusName)) {
+    return { error: `${fieldPath} must be one of: ${AVATAR_STATUSES.join(", ")}` };
+  }
+  return { avatarStatus: value as AvatarStatus };
+}
+
 function normalizeIdlePlan(value: unknown): { idlePlan?: IdlePlan; error?: string } {
   if (!isPlainObject(value)) {
     return { error: "idle plan payload must be an object" };
@@ -678,6 +715,7 @@ function normalizeIdlePlan(value: unknown): { idlePlan?: IdlePlan; error?: strin
     const name = rawStage.name;
     const purpose = rawStage.purpose;
     const pomodoroPhase = rawStage.pomodoroPhase;
+    const avatarStatus = rawStage.avatarStatus;
     const durationSeconds = rawStage.durationSeconds;
     const actions = rawStage.actions;
 
@@ -692,6 +730,10 @@ function normalizeIdlePlan(value: unknown): { idlePlan?: IdlePlan; error?: strin
         error: `stages[${stageIndex}].pomodoroPhase must be one of: ${IDLE_PLAN_POMODORO_PHASES.join(", ")}`,
       };
     }
+    const normalizedAvatarStatus = normalizeAvatarStatus(avatarStatus, `stages[${stageIndex}].avatarStatus`);
+    if (normalizedAvatarStatus.error || normalizedAvatarStatus.avatarStatus === undefined) {
+      return { error: normalizedAvatarStatus.error ?? `stages[${stageIndex}].avatarStatus is invalid` };
+    }
     if (!isPositiveInteger(durationSeconds)) {
       return { error: `stages[${stageIndex}].durationSeconds must be a positive integer` };
     }
@@ -776,6 +818,7 @@ function normalizeIdlePlan(value: unknown): { idlePlan?: IdlePlan; error?: strin
       name: name.trim(),
       purpose: purpose.trim(),
       pomodoroPhase,
+      avatarStatus: normalizedAvatarStatus.avatarStatus,
       durationSeconds,
       actions: normalizedActions,
     });
@@ -1001,6 +1044,7 @@ function buildKichiActionDescription(service?: KichiForwarderService): string {
     "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.",
     "For most work, prefer a sit pose and switch actions as the task moves between stages.",
+    "Set avatarStatus to the current avatar status: Idle, Busy, Activities, or Break.",
     "Set verify to true ONLY when the user explicitly requests a pose or action change. The server will confirm whether the avatar actually applied the requested pose. If it could not (e.g. no available seats), the result will contain the actual fallback pose so you can inform the user accurately. During routine sync steps, omit verify.",
     `stand actions: ${actions.stand.map((entry) => entry.name).join(", ")}`,
     `sit actions: ${actions.sit.map((entry) => entry.name).join(", ")}`,
@@ -1032,9 +1076,10 @@ function buildKichiIdlePlanDescription(): string {
     "2. Set the overall goal to that project. Do not use a vague atmosphere, a generic productivity task, or a catch-all routine summary as the goal.",
     "3. Break the full heartbeat interval into ordered stages. Each stage purpose must explain what you are actually doing in that stage as part of the same project, not just how you want to feel. Do not switch to unrelated tasks just to use more actions.",
     "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.",
+    "5. Set each stage avatarStatus to the avatar status for that stage: Idle, Busy, Activities, or Break.",
+    "6. Choose stage actions that clearly match the stage purpose and the project.",
+    "7. Write each action bubble as the current presented state, not a next step, plan, or instruction.",
+    "8. 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 your memory to recall what you did in past heartbeats and to stay consistent with your established personality and interests.",
     "Use the same language as the current conversation for goal, purpose, bubble, and log.",
     `stand actions: ${actions.stand.map((entry) => entry.name).join(", ")}`,
@@ -1059,6 +1104,7 @@ function buildKichiPrompt(): string {
     "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.",
+    "avatarStatus: set the current avatar status as Idle, Busy, Activities, or Break.",
     "",
     "kichi_clock: set countDown for tasks with 2+ steps or >10s work. Skip for quick one-shots.",
     "",
@@ -1166,18 +1212,29 @@ const plugin = {
     api.registerTool((ctx) => ({
       name: "kichi_join",
       label: "kichi_join",
-      description: "Join Kichi world with avatarId, the current bot name, a short bio, and personality tags",
+      description:
+        "Join Kichi world in the target environment with avatarId, the current bot name, a short bio, and personality tags. For test, pass host.",
       parameters: {
         type: "object",
         properties: {
           avatarId: { type: "string", description: "Avatar ID to join Kichi world" },
+          environment: {
+            type: "string",
+            enum: VALID_ENVIRONMENTS,
+            description:
+              "Target environment. kichi_join switches to this environment before joining.",
+          },
+          host: {
+            type: "string",
+            description: "Test host, required when environment is test and ignored otherwise",
+          },
           botName: {
             type: "string",
             description: "Current bot name to include in the join message",
           },
           bio: {
             type: "string",
-            description: "Short bio covering OpenClaw personality and role",
+            description: "Short bio extracted from SOUL.md, covering persona and idle plan goals if present",
           },
           tags: {
             type: "array",
@@ -1189,7 +1246,7 @@ const plugin = {
             description: "Optional join source identifier. Defaults to Kichi World join-source.json, then openclaw.",
           },
         },
-        required: ["botName", "bio"],
+        required: ["environment", "avatarId", "botName", "bio"],
       },
       execute: async (_toolCallId, params) => {
         const locator = resolveToolLocator(ctx);
@@ -1198,19 +1255,33 @@ const plugin = {
           return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
         }
         const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
-        let avatarId = (params as { avatarId?: string } | null)?.avatarId;
-        const botName = (params as { botName?: string } | null)?.botName?.trim();
-        const bio = (params as { bio?: string } | null)?.bio?.trim();
-        const rawSource = (params as { source?: unknown } | null)?.source;
-        const { tags, error: tagsError } = normalizeJoinTags(
-          (params as { tags?: unknown } | null)?.tags,
-        );
-        if (!avatarId) {
-          avatarId = service.readSavedAvatarId() ?? undefined;
+        const p = params as {
+          avatarId?: string;
+          environment?: unknown;
+          host?: unknown;
+          botName?: string;
+          bio?: string;
+          source?: unknown;
+          tags?: unknown;
+        } | null;
+        const target = resolveJoinEnvironmentHost({
+          environment: p?.environment,
+          host: p?.host,
+        });
+        if (target.error) {
+          return jsonResult({ success: false, error: target.error });
         }
-        if (!avatarId) {
-          return jsonResult({ success: false, error: "No avatarId" });
+        const currentStatus = service.getConnectionStatus();
+        let avatarId = p?.avatarId;
+        if (!avatarId && currentStatus.host === target.host) {
+          avatarId = service.readSavedAvatarId() ?? undefined;
         }
+        const botName = p?.botName?.trim();
+        const bio = p?.bio?.trim();
+        const rawSource = p?.source;
+        const { tags, error: tagsError } = normalizeJoinTags(
+          p?.tags,
+        );
         if (!botName) {
           return jsonResult({ success: false, error: "No botName" });
         }
@@ -1231,14 +1302,50 @@ const plugin = {
         if (tagsError) {
           return jsonResult({ success: false, error: tagsError });
         }
+        let leaveStatus;
+        const shouldLeaveCurrentConnection = currentStatus.connected && currentStatus.hasAuthKey && (
+          (!!currentStatus.host && currentStatus.host !== target.host) ||
+          (currentStatus.host === target.host && !!currentStatus.avatarId && !!avatarId && currentStatus.avatarId !== avatarId)
+        );
+        if (shouldLeaveCurrentConnection) {
+          try {
+            leaveStatus = await service.leave();
+          } catch (err) {
+            leaveStatus = {
+              success: false,
+              error: err instanceof Error ? err.message : String(err),
+            };
+          }
+        }
+        let switchStatus;
+        if (target.environment && target.host && service.getCurrentHost() !== target.host) {
+          switchStatus = await service.switchHost(target.host, target.environment);
+        }
+        if (!avatarId) {
+          avatarId = service.readSavedAvatarId() ?? undefined;
+        }
+        if (!avatarId) {
+          return jsonResult({ success: false, error: "No avatarId" });
+        }
         const result = await service.join(avatarId, botName, bio, tags ?? [], source);
         if (result.success) {
-          return jsonResult({ success: true, authKey: result.authKey });
+          return jsonResult({
+            success: true,
+            authKey: result.authKey,
+            ...(target.environment ? { environment: target.environment } : {}),
+            ...(target.host ? { host: target.host } : {}),
+            ...(switchStatus ? { switchStatus } : {}),
+            ...(leaveStatus ? { leaveStatus } : {}),
+          });
         }
         const failure = result as { success: false; error: string; errorCode?: string; errorMessage?: string };
         return jsonResult({
           success: false,
           error: failure.error,
+          ...(target.environment ? { environment: target.environment } : {}),
+          ...(target.host ? { host: target.host } : {}),
+          ...(switchStatus ? { switchStatus } : {}),
+          ...(leaveStatus ? { leaveStatus } : {}),
           ...(failure.errorCode ? { errorCode: failure.errorCode } : {}),
           ...(failure.errorMessage ? { errorMessage: failure.errorMessage } : {}),
         });
@@ -1260,7 +1367,7 @@ const plugin = {
           },
           host: {
             type: "string",
-            description: "Test node host (required for test environment, ignored otherwise)",
+            description: "Test host (required for test environment, ignored otherwise)",
           },
         },
         required: ["environment"],
@@ -1386,6 +1493,11 @@ const plugin = {
             description: "Action name for the selected pose (for example Sit Nicely, Typing with Keyboard, Reading, High Five, or Meditate)",
           },
           bubble: { type: "string", description: "Optional bubble text to display (max 5 words)" },
+          avatarStatus: {
+            type: "string",
+            description: "Current avatar status: Idle, Busy, Activities, or Break.",
+            enum: [...AVATAR_STATUSES],
+          },
           log: {
             type: "string",
             description:
@@ -1402,7 +1514,7 @@ const plugin = {
               "Optional poseable prop ID from RoomContext.PoseableProps (obtained via kichi_query_status or cached). When specified, the avatar is seated at this prop; when omitted, the server picks the nearest available prop.",
           },
         },
-        required: ["poseType", "action"],
+        required: ["poseType", "action", "avatarStatus"],
       },
       execute: async (_toolCallId, params) => {
         const locator = resolveToolLocator(ctx);
@@ -1411,10 +1523,11 @@ const plugin = {
           return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
         }
         const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
-        const { poseType, action, bubble, log, verify, propId } = (params || {}) as {
+        const { poseType, action, bubble, avatarStatus, log, verify, propId } = (params || {}) as {
           poseType?: string;
           action?: string;
           bubble?: string;
+          avatarStatus?: unknown;
           log?: string;
           verify?: boolean;
           propId?: string;
@@ -1428,6 +1541,10 @@ const plugin = {
             error: `Invalid poseType: ${poseType}. Must be stand, sit, lay, or floor`,
           });
         }
+        const normalizedAvatarStatus = normalizeAvatarStatus(avatarStatus, "avatarStatus");
+        if (normalizedAvatarStatus.error || normalizedAvatarStatus.avatarStatus === undefined) {
+          return jsonResult({ success: false, error: normalizedAvatarStatus.error ?? "avatarStatus is invalid" });
+        }
         if (!service.hasValidIdentity() || !service.isConnected()) {
           return jsonResult({ success: false, error: "Not connected to Kichi world" });
         }
@@ -1450,7 +1567,13 @@ const plugin = {
         if (verify) {
           try {
             const ack = await service.sendStatusVerified(
-              normalizedPoseType, matched.name, bubbleText, logText, playback, propId,
+              normalizedPoseType,
+              matched.name,
+              bubbleText,
+              logText,
+              playback,
+              normalizedAvatarStatus.avatarStatus,
+              propId,
             );
             if (ack.warning) {
               return jsonResult({
@@ -1469,6 +1592,7 @@ const plugin = {
             action: matched.name,
             bubble: bubbleText,
             log: logText,
+            avatarStatus: normalizedAvatarStatus.avatarStatus,
             propId,
           });
         }
@@ -1479,6 +1603,7 @@ const plugin = {
           action: matched.name,
           bubble: bubbleText,
           log: logText,
+          avatarStatus: normalizedAvatarStatus.avatarStatus,
           playback,
         });
       },
@@ -1586,6 +1711,11 @@ const plugin = {
                   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],
                 },
+                avatarStatus: {
+                  type: "string",
+                  description: "Avatar status for this stage: Idle, Busy, Activities, or Break.",
+                  enum: [...AVATAR_STATUSES],
+                },
                 durationSeconds: {
                   type: "number",
                   description: "Required duration in seconds for this stage.",
@@ -1625,7 +1755,7 @@ const plugin = {
                   },
                 },
               },
-              required: ["name", "purpose", "pomodoroPhase", "durationSeconds", "actions"],
+              required: ["name", "purpose", "pomodoroPhase", "avatarStatus", "durationSeconds", "actions"],
             },
           },
         },

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.2-beta.17",
+  "version": "0.1.2-beta.19",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
   "contracts": {

package/package.json

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

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, then call `kichi_switch_host` with both the environment and host. The host is persisted in `state.json` and reused on restart
+- `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
 
@@ -69,26 +69,23 @@ For install/onboarding/connect requests:
 
 Use this order unless the user asks for a different explicit action. For install/onboarding requests, follow `install.md` first.
 
-1. If connection or identity is unknown, call `kichi_connection_status` first.
-2. If the requested environment differs from the current environment, call `kichi_switch_host` with the target environment.
-3. If the requested `avatarId` differs from the current host's connected `avatarId`, call `kichi_leave` first when the old avatar is still joined, then call `kichi_join` with the requested `avatarId`.
-4. If no `authKey` is available, call `kichi_join`.
-5. If `authKey` exists but websocket is not open, call `kichi_rejoin` or wait for automatic reconnect and rejoin.
-6. Use `kichi_action`, `kichi_glance`, `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
 
@@ -98,7 +95,7 @@ kichi_switch_host(environment: "test", host: "192.168.1.100")
 ```
 
 - `environment`: required. One of `steam`, `steam-playtest`, `test`.
-- `host`: required for `test` environment, ignored otherwise. The test host is persisted in `state.json` and reused on restart.
+- `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.
 

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, then call `kichi_switch_host` with both the environment and 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 Files
 
@@ -23,17 +23,6 @@ Persist runtime state to the current agent's `state.json`:
 }
 ```
 
-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"
-}
-```
-
 ## Install
 
 1. Download the npm package archive:
@@ -64,7 +53,7 @@ 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`.
+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`.
@@ -72,11 +61,7 @@ When the user asks with one of the commands above, execute in this fixed order:
 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_connection_status`.
-12. If the current agent runtime environment does not match the requested one, call `kichi_switch_host` with the target environment (and host for test).
-13. 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`.
-14. Otherwise, if `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
-15. Call `kichi_connection_status` again and confirm connection and auth state.
+11. Call `kichi_join` with parsed `environment`, `host` for test, `avatarId`, `botName`, `bio`, and `tags`.
 
 ## Required Post-install Integration
 
@@ -85,7 +70,7 @@ 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/service.ts

@@ -5,6 +5,7 @@ import { randomUUID } from "node:crypto";
 import type { PluginLogger } from "openclaw/plugin-sdk";
 import type {
   ActionPlayback,
+  AvatarStatus,
   BotMessageHistoryEntry,
   BotMessagePayload,
   BotMessageReceivedPayload,
@@ -189,7 +190,15 @@ export class KichiForwarderService {
     });
   }
 
-  sendStatus(poseType: PoseType | "", action: string, bubble: string, log: string, playback: ActionPlayback, propId?: string): void {
+  sendStatus(
+    poseType: PoseType | "",
+    action: string,
+    bubble: string,
+    log: string,
+    playback: ActionPlayback,
+    avatarStatus: AvatarStatus,
+    propId?: string,
+  ): void {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) return;
     const payload: StatusPayload = {
       type: "status",
@@ -200,6 +209,7 @@ export class KichiForwarderService {
       bubble,
       log,
       playback,
+      avatarStatus,
       ...(propId ? { propId } : {}),
     };
     this.ws.send(JSON.stringify(payload));
@@ -211,6 +221,7 @@ export class KichiForwarderService {
     bubble: string,
     log: string,
     playback: ActionPlayback,
+    avatarStatus: AvatarStatus,
     propId?: string,
   ): Promise<StatusAckPayload> {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) {
@@ -226,6 +237,7 @@ export class KichiForwarderService {
       bubble,
       log,
       playback,
+      avatarStatus,
       ...(propId ? { propId } : {}),
     };
     return this.sendRequest<StatusAckPayload>(payload, "status_ack", 5000);

package/src/types.ts

@@ -2,6 +2,7 @@ export type KichiForwarderConfig = Record<string, never>;
 
 export type PoseType = "stand" | "sit" | "lay" | "floor";
 export type ActionPlaybackMode = "loop" | "once";
+export type AvatarStatus = "Idle" | "Busy" | "Activities" | "Break";
 export type ActionPlayback = {
   mode: ActionPlaybackMode;
   resumeAction?: string;
@@ -16,6 +17,7 @@ export type ActionResult = {
   poseType: PoseType;
   action: string;
   bubble: string;
+  avatarStatus: AvatarStatus;
   log?: string;
   propId?: string;
 };
@@ -120,6 +122,7 @@ export type StatusPayload = {
   bubble: string;
   log: string;
   playback: ActionPlayback;
+  avatarStatus: AvatarStatus;
   propId?: string;
 };
 
@@ -173,6 +176,7 @@ export type IdlePlanStage = {
   name: string;
   purpose: string;
   pomodoroPhase: IdlePlanPhase;
+  avatarStatus: AvatarStatus;
   durationSeconds: number;
   actions: IdlePlanStageAction[];
 };