@yahaha-studio/kichi-forwarder 0.1.2-beta.7 → 0.1.2-beta.8

package/dist/index.js

@@ -193,7 +193,7 @@ function resolveEnvironmentHost(environment) {
 }
 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));
+    service.sendStatus(status.poseType, actionDefinition.name, status.bubble || status.action, typeof status.log === "string" ? status.log.trim() : "", getActionPlayback(actionDefinition), status.propId);
 }
 function syncFixedStatus(service, status) {
     if (!service.hasValidIdentity() || !service.isConnected()) {
@@ -557,6 +557,7 @@ function normalizeIdlePlan(value) {
             const actionDurationSeconds = rawAction.durationSeconds;
             const bubble = rawAction.bubble;
             const log = rawAction.log;
+            const propId = rawAction.propId;
             if (!["stand", "sit", "lay", "floor"].includes(String(poseType))) {
                 return {
                     error: `stages[${stageIndex}].actions[${actionIndex}].poseType must be stand, sit, lay, or floor`,
@@ -601,6 +602,7 @@ function normalizeIdlePlan(value) {
                 durationSeconds: actionDurationSeconds,
                 bubble: bubble.trim(),
                 ...(typeof log === "string" && log.trim() ? { log: log.trim() } : {}),
+                ...(typeof propId === "string" && propId.trim() ? { propId: propId.trim() } : {}),
             });
         }
         if (stageActionDurationSeconds !== durationSeconds) {
@@ -797,9 +799,9 @@ function formatActionList(actions, playback) {
         .map((entry) => entry.name)
         .join(", ");
 }
-function buildKichiActionDescription() {
+function buildKichiActionDescription(service) {
     const actions = loadStaticConfig().actions;
-    return [
+    const lines = [
         "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.",
@@ -808,7 +810,13 @@ function buildKichiActionDescription() {
         `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");
+    ];
+    const roomContext = service.getCachedRoomContext();
+    const poseableProps = roomContext?.PoseableProps;
+    if (Array.isArray(poseableProps) && poseableProps.length > 0) {
+        lines.push("", "Cached RoomContext.PoseableProps (from last kichi_query_status):", JSON.stringify(poseableProps), "When using a sit or lay pose, pick the propId whose DisplayName best matches the current task context and whose OccupancyState is not fully_occupied. If no prop fits, omit propId.");
+    }
+    return lines.join("\n");
 }
 function buildKichiIdlePlanDescription() {
     const actions = loadStaticConfig().actions;
@@ -1089,7 +1097,7 @@ const plugin = {
         api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
             name: "kichi_action",
             label: "kichi_action",
-            description: buildKichiActionDescription(),
+            description: buildKichiActionDescription(service),
             parameters: {
                 type: "object",
                 properties: {
@@ -1107,11 +1115,15 @@ const plugin = {
                         type: "boolean",
                         description: "Set true ONLY when the user explicitly requests a pose or action. Omit during routine sync steps.",
                     },
+                    propId: {
+                        type: "string",
+                        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"],
             },
             execute: async (_toolCallId, params) => {
-                const { poseType, action, bubble, log, verify } = (params || {});
+                const { poseType, action, bubble, log, verify, propId } = (params || {});
                 if (!poseType || !action) {
                     return jsonResult({ success: false, error: "poseType and action parameters are required" });
                 }
@@ -1139,7 +1151,7 @@ const plugin = {
                 const playback = getActionPlayback(matched);
                 if (verify) {
                     try {
-                        const ack = await service.sendStatusVerified(normalizedPoseType, matched.name, bubbleText, logText, playback);
+                        const ack = await service.sendStatusVerified(normalizedPoseType, matched.name, bubbleText, logText, playback, propId);
                         if (ack.warning) {
                             return jsonResult({
                                 success: true,
@@ -1159,6 +1171,7 @@ const plugin = {
                         action: matched.name,
                         bubble: bubbleText,
                         log: logText,
+                        propId,
                     });
                 }
                 return jsonResult({
@@ -1239,6 +1252,10 @@ const plugin = {
                                                 type: "string",
                                                 description: "Optional log content for this action. Use the same language as the current conversation.",
                                             },
+                                            propId: {
+                                                type: "string",
+                                                description: "Optional poseable prop ID from RoomContext.PoseableProps. When specified, the avatar is seated at this prop.",
+                                            },
                                         },
                                         required: ["poseType", "action", "durationSeconds", "bubble"],
                                     },
@@ -1383,7 +1400,7 @@ const plugin = {
         api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
             name: "kichi_query_status",
             label: "kichi_query_status",
-            description: "Query Kichi room and avatar status — includes room personnel, notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, and `hasCreatedMusicAlbumToday`. Use this when the user asks to check kichi status, room status, or who is in the room. Also use this before creating a new note or daily recommended music album. For heartbeat planning, use the returned idlePlan as reference when shaping the next idle plan.",
+            description: "Query Kichi room and avatar status — includes room personnel, notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, `hasCreatedMusicAlbumToday`, and RoomContext.PoseableProps (poseable props with PropId, DisplayName, SupportedPoseTypes, OccupancyState). The PoseableProps list is cached internally so that kichi_action can reference a propId during regular work sync without re-querying. Use this when the user asks to check kichi status, room status, or who is in the room. Also use this before creating a new note or daily recommended music album. For heartbeat planning, use the returned idlePlan as reference when shaping the next idle plan.",
             parameters: {
                 type: "object",
                 properties: {

package/dist/src/service.js

@@ -17,6 +17,7 @@ export class KichiForwarderService {
     joinResolve = null;
     pendingRequests = new Map();
     onBotMessageReceived = null;
+    cachedRoomContext = null;
     constructor(logger, options) {
         this.logger = logger;
         this.options = options;
@@ -91,7 +92,7 @@ export class KichiForwarderService {
             }, 10000);
         });
     }
-    sendStatus(poseType, action, bubble, log, playback) {
+    sendStatus(poseType, action, bubble, log, playback, propId) {
         if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN)
             return;
         const payload = {
@@ -103,10 +104,11 @@ export class KichiForwarderService {
             bubble,
             log,
             playback,
+            ...(propId ? { propId } : {}),
         };
         this.ws.send(JSON.stringify(payload));
     }
-    async sendStatusVerified(poseType, action, bubble, log, playback) {
+    async sendStatusVerified(poseType, action, bubble, log, playback, propId) {
         if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) {
             throw new Error("Kichi websocket is not connected");
         }
@@ -120,6 +122,7 @@ export class KichiForwarderService {
             bubble,
             log,
             playback,
+            ...(propId ? { propId } : {}),
         };
         return this.sendRequest(payload, "status_ack", 5000);
     }
@@ -181,7 +184,11 @@ export class KichiForwarderService {
             avatarId: identity.avatarId,
             authKey: identity.authKey,
         };
-        return this.sendRequest(payload, "query_status_result");
+        const result = await this.sendRequest(payload, "query_status_result");
+        if (result.RoomContext && typeof result.RoomContext === "object") {
+            this.cachedRoomContext = result.RoomContext;
+        }
+        return result;
     }
     createNotesBoardNote(propId, data) {
         const identity = this.requireIdentity();
@@ -250,6 +257,7 @@ export class KichiForwarderService {
         return this.sendRequest(payload, "bot_message_ack", 5000);
     }
     isConnected() { return this.ws?.readyState === WebSocket.OPEN && !!this.identity?.authKey; }
+    getCachedRoomContext() { return this.cachedRoomContext; }
     hasValidIdentity() { return !!this.identity?.avatarId && !!this.identity?.authKey; }
     isLlmRuntimeEnabled() {
         return this.readStateFile()?.llmRuntimeEnabled ?? DEFAULT_LLM_RUNTIME_ENABLED;

package/index.ts

@@ -264,6 +264,7 @@ function sendStatusUpdate(service: KichiForwarderService, status: ActionResult):
     status.bubble || status.action,
     typeof status.log === "string" ? status.log.trim() : "",
     getActionPlayback(actionDefinition),
+    status.propId,
   );
 }
 
@@ -712,6 +713,7 @@ function normalizeIdlePlan(value: unknown): { idlePlan?: IdlePlan; error?: strin
       const actionDurationSeconds = rawAction.durationSeconds;
       const bubble = rawAction.bubble;
       const log = rawAction.log;
+      const propId = rawAction.propId;
 
       if (!["stand", "sit", "lay", "floor"].includes(String(poseType))) {
         return {
@@ -759,6 +761,7 @@ function normalizeIdlePlan(value: unknown): { idlePlan?: IdlePlan; error?: strin
         durationSeconds: actionDurationSeconds,
         bubble: bubble.trim(),
         ...(typeof log === "string" && log.trim() ? { log: log.trim() } : {}),
+        ...(typeof propId === "string" && propId.trim() ? { propId: propId.trim() } : {}),
       });
     }
 
@@ -992,9 +995,9 @@ function formatActionList(actions: ActionDefinition[], playback: ActionPlayback[
     .join(", ");
 }
 
-function buildKichiActionDescription(): string {
+function buildKichiActionDescription(service: KichiForwarderService): string {
   const actions = loadStaticConfig().actions;
-  return [
+  const lines = [
     "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.",
@@ -1003,7 +1006,20 @@ function buildKichiActionDescription(): string {
     `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");
+  ];
+
+  const roomContext = service.getCachedRoomContext();
+  const poseableProps = roomContext?.PoseableProps;
+  if (Array.isArray(poseableProps) && poseableProps.length > 0) {
+    lines.push(
+      "",
+      "Cached RoomContext.PoseableProps (from last kichi_query_status):",
+      JSON.stringify(poseableProps),
+      "When using a sit or lay pose, pick the propId whose DisplayName best matches the current task context and whose OccupancyState is not fully_occupied. If no prop fits, omit propId.",
+    );
+  }
+
+  return lines.join("\n");
 }
 
 function buildKichiIdlePlanDescription(): string {
@@ -1312,7 +1328,7 @@ const plugin = {
     api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_action",
       label: "kichi_action",
-      description: buildKichiActionDescription(),
+      description: buildKichiActionDescription(service),
       parameters: {
         type: "object",
         properties: {
@@ -1332,16 +1348,22 @@ const plugin = {
             description:
               "Set true ONLY when the user explicitly requests a pose or action. Omit during routine sync steps.",
           },
+          propId: {
+            type: "string",
+            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"],
       },
       execute: async (_toolCallId, params) => {
-        const { poseType, action, bubble, log, verify } = (params || {}) as {
+        const { poseType, action, bubble, log, verify, propId } = (params || {}) as {
           poseType?: string;
           action?: string;
           bubble?: string;
           log?: string;
           verify?: boolean;
+          propId?: string;
         };
         if (!poseType || !action) {
           return jsonResult({ success: false, error: "poseType and action parameters are required" });
@@ -1374,7 +1396,7 @@ const plugin = {
         if (verify) {
           try {
             const ack = await service.sendStatusVerified(
-              normalizedPoseType, matched.name, bubbleText, logText, playback,
+              normalizedPoseType, matched.name, bubbleText, logText, playback, propId,
             );
             if (ack.warning) {
               return jsonResult({
@@ -1393,6 +1415,7 @@ const plugin = {
             action: matched.name,
             bubble: bubbleText,
             log: logText,
+            propId,
           });
         }
 
@@ -1474,6 +1497,10 @@ const plugin = {
                         type: "string",
                         description: "Optional log content for this action. Use the same language as the current conversation.",
                       },
+                      propId: {
+                        type: "string",
+                        description: "Optional poseable prop ID from RoomContext.PoseableProps. When specified, the avatar is seated at this prop.",
+                      },
                     },
                     required: ["poseType", "action", "durationSeconds", "bubble"],
                   },
@@ -1629,7 +1656,7 @@ const plugin = {
       name: "kichi_query_status",
       label: "kichi_query_status",
       description:
-        "Query Kichi room and avatar status — includes room personnel, notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, and `hasCreatedMusicAlbumToday`. Use this when the user asks to check kichi status, room status, or who is in the room. Also use this before creating a new note or daily recommended music album. For heartbeat planning, use the returned idlePlan as reference when shaping the next idle plan.",
+        "Query Kichi room and avatar status — includes room personnel, notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, `hasCreatedMusicAlbumToday`, and RoomContext.PoseableProps (poseable props with PropId, DisplayName, SupportedPoseTypes, OccupancyState). The PoseableProps list is cached internally so that kichi_action can reference a propId during regular work sync without re-querying. Use this when the user asks to check kichi status, room status, or who is in the room. Also use this before creating a new note or daily recommended music album. For heartbeat planning, use the returned idlePlan as reference when shaping the next idle plan.",
       parameters: {
         type: "object",
         properties: {

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

package/package.json

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

@@ -83,6 +83,7 @@ export class KichiForwarderService {
     }
   >();
   onBotMessageReceived: BotMessageReceivedHandler | null = null;
+  private cachedRoomContext: Record<string, unknown> | null = null;
 
   constructor(
     private logger: PluginLogger,
@@ -166,7 +167,7 @@ export class KichiForwarderService {
     });
   }
 
-  sendStatus(poseType: PoseType | "", action: string, bubble: string, log: string, playback: ActionPlayback): void {
+  sendStatus(poseType: PoseType | "", action: string, bubble: string, log: string, playback: ActionPlayback, propId?: string): void {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) return;
     const payload: StatusPayload = {
       type: "status",
@@ -177,6 +178,7 @@ export class KichiForwarderService {
       bubble,
       log,
       playback,
+      ...(propId ? { propId } : {}),
     };
     this.ws.send(JSON.stringify(payload));
   }
@@ -187,6 +189,7 @@ export class KichiForwarderService {
     bubble: string,
     log: string,
     playback: ActionPlayback,
+    propId?: string,
   ): Promise<StatusAckPayload> {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) {
       throw new Error("Kichi websocket is not connected");
@@ -201,6 +204,7 @@ export class KichiForwarderService {
       bubble,
       log,
       playback,
+      ...(propId ? { propId } : {}),
     };
     return this.sendRequest<StatusAckPayload>(payload, "status_ack", 5000);
   }
@@ -267,7 +271,11 @@ export class KichiForwarderService {
       avatarId: identity.avatarId,
       authKey: identity.authKey,
     };
-    return this.sendRequest<QueryStatusResultPayload>(payload, "query_status_result");
+    const result = await this.sendRequest<QueryStatusResultPayload>(payload, "query_status_result");
+    if (result.RoomContext && typeof result.RoomContext === "object") {
+      this.cachedRoomContext = result.RoomContext as Record<string, unknown>;
+    }
+    return result;
   }
 
   createNotesBoardNote(propId: string, data: string): void {
@@ -350,6 +358,8 @@ export class KichiForwarderService {
 
   isConnected(): boolean { return this.ws?.readyState === WebSocket.OPEN && !!this.identity?.authKey; }
 
+  getCachedRoomContext(): Record<string, unknown> | null { return this.cachedRoomContext; }
+
   hasValidIdentity(): boolean { return !!this.identity?.avatarId && !!this.identity?.authKey; }
 
   isLlmRuntimeEnabled(): boolean {

package/src/types.ts

@@ -17,6 +17,7 @@ export type ActionResult = {
   action: string;
   bubble: string;
   log?: string;
+  propId?: string;
 };
 
 export type KichiStaticConfig = {
@@ -117,6 +118,7 @@ export type StatusPayload = {
   bubble: string;
   log: string;
   playback: ActionPlayback;
+  propId?: string;
 };
 
 export type StatusAckPayload = {
@@ -124,6 +126,7 @@ export type StatusAckPayload = {
   requestId: string;
   poseType: PoseType | "";
   action: string;
+  requestedPropId?: string;
   warning?: string;
 };
 
@@ -144,6 +147,7 @@ export type IdlePlanStageAction = {
   durationSeconds: number;
   bubble: string;
   log?: string;
+  propId?: string;
 };
 
 export type IdlePlanStage = {