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

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;
@@ -850,17 +858,6 @@ function buildKichiPrompt() {
         "User opt-out, Kichi config/test work, and explicit pose requests take priority over sync.",
     ].join("\n");
 }
-function createAgentScopedTool(runtimeManager, factory) {
-    return (ctx) => {
-        const locator = resolveToolLocator(ctx);
-        const agentId = runtimeManager.resolveRuntimeAgentId(locator);
-        if (!agentId) {
-            throw new Error("Failed to resolve agent-scoped Kichi runtime");
-        }
-        const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
-        return factory(service, ctx);
-    };
-}
 const GLOBAL_RUNTIME_MANAGER_KEY = "__kichi_forwarder_runtime_manager__";
 function getRuntimeManager(logger) {
     const globalState = globalThis;
@@ -881,6 +878,11 @@ const plugin = {
     configSchema: { parse },
     register(api) {
         const runtimeManager = getRuntimeManager(api.logger);
+        runtimeManager.setEnvironmentHostResolver((environment) => {
+            const config = loadEnvironmentsConfig();
+            const host = config[environment];
+            return typeof host === "string" && host.trim() ? host : null;
+        });
         registerPluginHooks(api, runtimeManager);
         const musicTitleEnum = getMusicTitleEnum();
         runtimeManager.setBotMessageHandler((service, msg) => {
@@ -928,11 +930,6 @@ const plugin = {
             id: "kichi-forwarder",
             start: (ctx) => {
                 parse(ctx.config.plugins?.entries?.["kichi-forwarder"]?.config);
-                runtimeManager.setEnvironmentHostResolver((environment) => {
-                    const config = loadEnvironmentsConfig();
-                    const host = config[environment];
-                    return typeof host === "string" && host.trim() ? host : null;
-                });
                 runtimeManager.initializeStartupRuntimes();
             },
             stop: () => {
@@ -943,7 +940,7 @@ const plugin = {
                 }
             },
         });
-        api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+        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",
@@ -968,6 +965,12 @@ const plugin = {
                 required: ["botName", "bio"],
             },
             execute: async (_toolCallId, params) => {
+                const locator = resolveToolLocator(ctx);
+                const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+                if (!agentId) {
+                    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();
@@ -999,54 +1002,58 @@ const plugin = {
                     ...(failure.errorMessage ? { errorMessage: failure.errorMessage } : {}),
                 });
             },
-        })));
-        api.registerTool((ctx) => {
-            const locator = resolveToolLocator(ctx);
-            const agentId = runtimeManager.resolveRuntimeAgentId(locator);
-            if (!agentId) {
-                throw new Error("Failed to resolve agent-scoped Kichi runtime");
-            }
-            const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
-            return ({
-                name: "kichi_switch_host",
-                label: "kichi_switch_host",
-                description: "Switch Kichi runtime environment and reconnect immediately without restarting the gateway. Host is resolved from config/environments.json.",
-                parameters: {
-                    type: "object",
-                    properties: {
-                        environment: {
-                            type: "string",
-                            enum: VALID_ENVIRONMENTS,
-                            description: "Target environment: steam, steam-playtest, or test",
-                        },
+        }));
+        api.registerTool((ctx) => ({
+            name: "kichi_switch_host",
+            label: "kichi_switch_host",
+            description: "Switch Kichi runtime environment and reconnect immediately without restarting the gateway. Host is resolved from config/environments.json.",
+            parameters: {
+                type: "object",
+                properties: {
+                    environment: {
+                        type: "string",
+                        enum: VALID_ENVIRONMENTS,
+                        description: "Target environment: steam, steam-playtest, or test",
                     },
-                    required: ["environment"],
                 },
-                execute: async (_toolCallId, params) => {
-                    const environment = params?.environment;
-                    if (!isKichiEnvironment(environment)) {
-                        return jsonResult({ success: false, error: `environment must be one of: ${VALID_ENVIRONMENTS.join(", ")}` });
-                    }
-                    const resolved = resolveEnvironmentHost(environment);
-                    if (resolved.error) {
-                        return jsonResult({ success: false, error: resolved.error });
-                    }
-                    const status = await service.switchHost(resolved.host, environment);
-                    return jsonResult({
-                        success: true,
-                        environment,
-                        host: resolved.host,
-                        status,
-                    });
-                },
-            });
-        });
-        api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+                required: ["environment"],
+            },
+            execute: async (_toolCallId, params) => {
+                const locator = resolveToolLocator(ctx);
+                const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+                if (!agentId) {
+                    return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+                }
+                const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
+                const environment = params?.environment;
+                if (!isKichiEnvironment(environment)) {
+                    return jsonResult({ success: false, error: `environment must be one of: ${VALID_ENVIRONMENTS.join(", ")}` });
+                }
+                const resolved = resolveEnvironmentHost(environment);
+                if (resolved.error) {
+                    return jsonResult({ success: false, error: resolved.error });
+                }
+                const status = await service.switchHost(resolved.host, environment);
+                return jsonResult({
+                    success: true,
+                    environment,
+                    host: resolved.host,
+                    status,
+                });
+            },
+        }));
+        api.registerTool((ctx) => ({
             name: "kichi_rejoin",
             label: "kichi_rejoin",
             description: "Request an immediate rejoin attempt with saved avatarId/authKey. Rejoin is also sent automatically after reconnect.",
             parameters: { type: "object", properties: {} },
-            execute: async () => {
+            execute: async (_toolCallId, _params) => {
+                const locator = resolveToolLocator(ctx);
+                const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+                if (!agentId) {
+                    return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+                }
+                const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
                 const result = service.requestRejoin();
                 return jsonResult({
                     success: result.accepted,
@@ -1054,13 +1061,19 @@ const plugin = {
                     status: service.getConnectionStatus(),
                 });
             },
-        })));
-        api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+        }));
+        api.registerTool((ctx) => ({
             name: "kichi_leave",
             label: "kichi_leave",
             description: "Leave Kichi world",
             parameters: { type: "object", properties: {} },
-            execute: async () => {
+            execute: async (_toolCallId, _params) => {
+                const locator = resolveToolLocator(ctx);
+                const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+                if (!agentId) {
+                    return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+                }
+                const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
                 const result = await service.leave();
                 if (result.success) {
                     return jsonResult({ success: true });
@@ -1073,105 +1086,126 @@ const plugin = {
                     ...(failure.errorMessage ? { errorMessage: failure.errorMessage } : {}),
                 });
             },
-        })));
-        api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+        }));
+        api.registerTool((ctx) => ({
             name: "kichi_connection_status",
             label: "kichi_connection_status",
             description: "Check WebSocket connection status and identity readiness only. Does NOT return room info, avatar state, or personnel — use kichi_query_status for that.",
             parameters: { type: "object", properties: {} },
-            execute: async () => {
+            execute: async (_toolCallId, _params) => {
+                const locator = resolveToolLocator(ctx);
+                const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+                if (!agentId) {
+                    return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+                }
+                const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
                 return jsonResult({
                     success: true,
                     status: service.getConnectionStatus(),
                 });
             },
-        })));
-        api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
-            name: "kichi_action",
-            label: "kichi_action",
-            description: buildKichiActionDescription(),
-            parameters: {
-                type: "object",
-                properties: {
-                    poseType: { type: "string", description: "Pose type: stand, sit, lay, or floor" },
-                    action: {
-                        type: "string",
-                        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)" },
-                    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.",
-                    },
-                    verify: {
-                        type: "boolean",
-                        description: "Set true ONLY when the user explicitly requests a pose or action. Omit during routine sync steps.",
+        }));
+        api.registerTool((ctx) => {
+            const locator = resolveToolLocator(ctx);
+            const existingService = runtimeManager.getRuntime(locator);
+            return ({
+                name: "kichi_action",
+                label: "kichi_action",
+                description: buildKichiActionDescription(existingService ?? undefined),
+                parameters: {
+                    type: "object",
+                    properties: {
+                        poseType: { type: "string", description: "Pose type: stand, sit, lay, or floor" },
+                        action: {
+                            type: "string",
+                            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)" },
+                        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.",
+                        },
+                        verify: {
+                            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"],
                 },
-                required: ["poseType", "action"],
-            },
-            execute: async (_toolCallId, params) => {
-                const { poseType, action, bubble, log, verify } = (params || {});
-                if (!poseType || !action) {
-                    return jsonResult({ success: false, error: "poseType and action parameters are required" });
-                }
-                if (!["stand", "sit", "lay", "floor"].includes(poseType)) {
-                    return jsonResult({
-                        success: false,
-                        error: `Invalid poseType: ${poseType}. Must be stand, sit, lay, or floor`,
-                    });
-                }
-                if (!service.hasValidIdentity() || !service.isConnected()) {
-                    return jsonResult({ success: false, error: "Not connected to Kichi world" });
-                }
-                const normalizedPoseType = poseType;
-                const poseActions = loadStaticConfig().actions[normalizedPoseType];
-                const matched = poseActions.find((entry) => entry.name.toLowerCase() === action.toLowerCase());
-                if (!matched) {
-                    return jsonResult({
-                        success: false,
-                        error: `Unknown action "${action}" for poseType "${poseType}"`,
-                        available: poseActions.map((entry) => entry.name),
-                    });
-                }
-                const bubbleText = typeof bubble === "string" && bubble.trim() ? bubble.trim() : matched.name;
-                const logText = typeof log === "string" ? log.trim() : "";
-                const playback = getActionPlayback(matched);
-                if (verify) {
-                    try {
-                        const ack = await service.sendStatusVerified(normalizedPoseType, matched.name, bubbleText, logText, playback);
-                        if (ack.warning) {
-                            return jsonResult({
-                                success: true,
-                                requested: { poseType: normalizedPoseType, action: matched.name },
-                                actual: { poseType: ack.poseType, action: ack.action },
-                                warning: ack.warning,
-                            });
+                execute: async (_toolCallId, params) => {
+                    const locator = resolveToolLocator(ctx);
+                    const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+                    if (!agentId) {
+                        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 || {});
+                    if (!poseType || !action) {
+                        return jsonResult({ success: false, error: "poseType and action parameters are required" });
+                    }
+                    if (!["stand", "sit", "lay", "floor"].includes(poseType)) {
+                        return jsonResult({
+                            success: false,
+                            error: `Invalid poseType: ${poseType}. Must be stand, sit, lay, or floor`,
+                        });
+                    }
+                    if (!service.hasValidIdentity() || !service.isConnected()) {
+                        return jsonResult({ success: false, error: "Not connected to Kichi world" });
+                    }
+                    const normalizedPoseType = poseType;
+                    const poseActions = loadStaticConfig().actions[normalizedPoseType];
+                    const matched = poseActions.find((entry) => entry.name.toLowerCase() === action.toLowerCase());
+                    if (!matched) {
+                        return jsonResult({
+                            success: false,
+                            error: `Unknown action "${action}" for poseType "${poseType}"`,
+                            available: poseActions.map((entry) => entry.name),
+                        });
+                    }
+                    const bubbleText = typeof bubble === "string" && bubble.trim() ? bubble.trim() : matched.name;
+                    const logText = typeof log === "string" ? log.trim() : "";
+                    const playback = getActionPlayback(matched);
+                    if (verify) {
+                        try {
+                            const ack = await service.sendStatusVerified(normalizedPoseType, matched.name, bubbleText, logText, playback, propId);
+                            if (ack.warning) {
+                                return jsonResult({
+                                    success: true,
+                                    requested: { poseType: normalizedPoseType, action: matched.name },
+                                    actual: { poseType: ack.poseType, action: ack.action },
+                                    warning: ack.warning,
+                                });
+                            }
+                        }
+                        catch {
+                            // Server not updated or timeout — fall through to normal success
                         }
                     }
-                    catch {
-                        // Server not updated or timeout — fall through to normal success
+                    else {
+                        sendStatusUpdate(service, {
+                            poseType: normalizedPoseType,
+                            action: matched.name,
+                            bubble: bubbleText,
+                            log: logText,
+                            propId,
+                        });
                     }
-                }
-                else {
-                    sendStatusUpdate(service, {
+                    return jsonResult({
+                        success: true,
                         poseType: normalizedPoseType,
                         action: matched.name,
                         bubble: bubbleText,
                         log: logText,
+                        playback,
                     });
-                }
-                return jsonResult({
-                    success: true,
-                    poseType: normalizedPoseType,
-                    action: matched.name,
-                    bubble: bubbleText,
-                    log: logText,
-                    playback,
-                });
-            },
-        })));
-        api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+                },
+            });
+        });
+        api.registerTool((ctx) => ({
             name: "kichi_idle_plan",
             label: "kichi_idle_plan",
             description: buildKichiIdlePlanDescription(),
@@ -1239,6 +1273,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"],
                                     },
@@ -1251,6 +1289,12 @@ const plugin = {
                 required: ["heartbeatIntervalSeconds", "goal", "stages"],
             },
             execute: async (_toolCallId, params) => {
+                const locator = resolveToolLocator(ctx);
+                const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+                if (!agentId) {
+                    return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+                }
+                const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
                 const { idlePlan, error } = normalizeIdlePlan(params);
                 if (!idlePlan) {
                     return jsonResult({ success: false, error: error ?? "Invalid idle plan payload" });
@@ -1276,8 +1320,8 @@ const plugin = {
                     stages: idlePlan.stages,
                 });
             },
-        })));
-        api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+        }));
+        api.registerTool((ctx) => ({
             name: "kichi_clock",
             label: "kichi_clock",
             description: "Send clock commands to Kichi world. Supported actions are set and stop.",
@@ -1346,6 +1390,12 @@ const plugin = {
                 required: ["action"],
             },
             execute: async (_toolCallId, params) => {
+                const locator = resolveToolLocator(ctx);
+                const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+                if (!agentId) {
+                    return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+                }
+                const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
                 const { action, requestId, clock } = (params || {});
                 if (!isClockAction(action)) {
                     return jsonResult({
@@ -1379,11 +1429,11 @@ const plugin = {
                     ...(normalizedClock ? { clock: normalizedClock } : {}),
                 });
             },
-        })));
-        api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+        }));
+        api.registerTool((ctx) => ({
             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: {
@@ -1394,6 +1444,12 @@ const plugin = {
                 },
             },
             execute: async (_toolCallId, params) => {
+                const locator = resolveToolLocator(ctx);
+                const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+                if (!agentId) {
+                    return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+                }
+                const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
                 const requestId = params?.requestId;
                 if (requestId !== undefined && typeof requestId !== "string") {
                     return jsonResult({ success: false, error: "requestId must be a string when provided" });
@@ -1412,8 +1468,8 @@ const plugin = {
                     });
                 }
             },
-        })));
-        api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+        }));
+        api.registerTool((ctx) => ({
             name: "kichi_music_album_create",
             label: "kichi_music_album_create",
             description: buildMusicAlbumToolDescription(),
@@ -1440,6 +1496,12 @@ const plugin = {
                 required: ["albumTitle", "musicTitles"],
             },
             execute: async (_toolCallId, params) => {
+                const locator = resolveToolLocator(ctx);
+                const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+                if (!agentId) {
+                    return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+                }
+                const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
                 const { requestId, albumTitle, musicTitles, } = (params || {});
                 if (requestId !== undefined && typeof requestId !== "string") {
                     return jsonResult({ success: false, error: "requestId must be a string when provided" });
@@ -1486,8 +1548,8 @@ const plugin = {
                     });
                 }
             },
-        })));
-        api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+        }));
+        api.registerTool((ctx) => ({
             name: "kichi_noteboard_create",
             label: "kichi_noteboard_create",
             description: "Create a new note on a specific Kichi note board. Prefer querying first so you can avoid duplicate posts and respect rate limits.",
@@ -1506,6 +1568,12 @@ const plugin = {
                 required: ["propId", "data"],
             },
             execute: async (_toolCallId, params) => {
+                const locator = resolveToolLocator(ctx);
+                const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+                if (!agentId) {
+                    return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+                }
+                const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
                 const { propId, data } = (params || {});
                 if (typeof propId !== "string" || !propId.trim()) {
                     return jsonResult({ success: false, error: "propId is required" });
@@ -1533,8 +1601,8 @@ const plugin = {
                     });
                 }
             },
-        })));
-        api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+        }));
+        api.registerTool((ctx) => ({
             name: "kichi_bot_message",
             label: "kichi_bot_message",
             description: "Send a message to another bot in the same Kichi world. The bubble is the visible message content. Do not repeat what has already been said in the conversation history. When targeting a specific bot by name, call kichi_query_status first to resolve their avatarId. Only use \"*\" when broadcasting to all bots without a specific target.",
@@ -1570,6 +1638,12 @@ const plugin = {
                 required: ["toAvatarId", "depth", "bubble"],
             },
             execute: async (_toolCallId, params) => {
+                const locator = resolveToolLocator(ctx);
+                const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+                if (!agentId) {
+                    return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+                }
+                const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
                 const { toAvatarId, depth, bubble, poseType, action, log } = (params || {});
                 if (typeof toAvatarId !== "string" || !toAvatarId.trim()) {
                     return jsonResult({ success: false, error: "toAvatarId is required" });
@@ -1601,7 +1675,7 @@ const plugin = {
                     return jsonResult({ success: false, error: `Failed to send bot message: ${error}` });
                 }
             },
-        })));
+        }));
     },
 };
 export default plugin;

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

@@ -1,7 +1,6 @@
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import type {
-  AnyAgentTool,
   OpenClawPluginApi,
 } from "openclaw/plugin-sdk";
 import type { OpenClawPluginToolContext } from "openclaw/plugin-sdk/core";
@@ -264,6 +263,7 @@ function sendStatusUpdate(service: KichiForwarderService, status: ActionResult):
     status.bubble || status.action,
     typeof status.log === "string" ? status.log.trim() : "",
     getActionPlayback(actionDefinition),
+    status.propId,
   );
 }
 
@@ -712,6 +712,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 +760,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 +994,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 +1005,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 {
@@ -1048,20 +1063,6 @@ function buildKichiPrompt(): string {
   ].join("\n");
 }
 
-function createAgentScopedTool(
-  runtimeManager: KichiRuntimeManager,
-  factory: (service: KichiForwarderService, ctx: OpenClawPluginToolContext) => AnyAgentTool,
-) {
-  return (ctx: OpenClawPluginToolContext) => {
-    const locator = resolveToolLocator(ctx);
-    const agentId = runtimeManager.resolveRuntimeAgentId(locator);
-    if (!agentId) {
-      throw new Error("Failed to resolve agent-scoped Kichi runtime");
-    }
-    const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
-    return factory(service, ctx);
-  };
-}
 
 const GLOBAL_RUNTIME_MANAGER_KEY = "__kichi_forwarder_runtime_manager__";
 
@@ -1091,6 +1092,13 @@ const plugin = {
 
   register(api: OpenClawPluginApi) {
     const runtimeManager = getRuntimeManager(api.logger);
+
+    runtimeManager.setEnvironmentHostResolver((environment) => {
+      const config = loadEnvironmentsConfig();
+      const host = config[environment];
+      return typeof host === "string" && host.trim() ? host : null;
+    });
+
     registerPluginHooks(api, runtimeManager);
     const musicTitleEnum = getMusicTitleEnum();
 
@@ -1139,11 +1147,6 @@ const plugin = {
       id: "kichi-forwarder",
       start: (ctx) => {
         parse(ctx.config.plugins?.entries?.["kichi-forwarder"]?.config);
-        runtimeManager.setEnvironmentHostResolver((environment) => {
-          const config = loadEnvironmentsConfig();
-          const host = config[environment];
-          return typeof host === "string" && host.trim() ? host : null;
-        });
         runtimeManager.initializeStartupRuntimes();
       },
       stop: () => {
@@ -1155,7 +1158,7 @@ const plugin = {
       },
     });
 
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    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",
@@ -1180,6 +1183,12 @@ const plugin = {
         required: ["botName", "bio"],
       },
       execute: async (_toolCallId, params) => {
+        const locator = resolveToolLocator(ctx);
+        const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+        if (!agentId) {
+          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();
@@ -1213,16 +1222,9 @@ const plugin = {
           ...(failure.errorMessage ? { errorMessage: failure.errorMessage } : {}),
         });
       },
-    })));
+    }));
 
-    api.registerTool((ctx: OpenClawPluginToolContext) => {
-      const locator = resolveToolLocator(ctx);
-      const agentId = runtimeManager.resolveRuntimeAgentId(locator);
-      if (!agentId) {
-        throw new Error("Failed to resolve agent-scoped Kichi runtime");
-      }
-      const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
-      return ({
+    api.registerTool((ctx) => ({
       name: "kichi_switch_host",
       label: "kichi_switch_host",
       description:
@@ -1239,6 +1241,12 @@ const plugin = {
         required: ["environment"],
       },
       execute: async (_toolCallId, params) => {
+        const locator = resolveToolLocator(ctx);
+        const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+        if (!agentId) {
+          return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+        }
+        const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
         const environment = (params as { environment?: unknown } | null)?.environment;
         if (!isKichiEnvironment(environment)) {
           return jsonResult({ success: false, error: `environment must be one of: ${VALID_ENVIRONMENTS.join(", ")}` });
@@ -1257,16 +1265,21 @@ const plugin = {
           status,
         });
       },
-      });
-    });
+    }));
 
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    api.registerTool((ctx) => ({
       name: "kichi_rejoin",
       label: "kichi_rejoin",
       description:
         "Request an immediate rejoin attempt with saved avatarId/authKey. Rejoin is also sent automatically after reconnect.",
       parameters: { type: "object", properties: {} },
-      execute: async () => {
+      execute: async (_toolCallId, _params) => {
+        const locator = resolveToolLocator(ctx);
+        const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+        if (!agentId) {
+          return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+        }
+        const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
         const result = service.requestRejoin();
         return jsonResult({
           success: result.accepted,
@@ -1274,14 +1287,20 @@ const plugin = {
           status: service.getConnectionStatus(),
         });
       },
-    })));
+    }));
 
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    api.registerTool((ctx) => ({
       name: "kichi_leave",
       label: "kichi_leave",
       description: "Leave Kichi world",
       parameters: { type: "object", properties: {} },
-      execute: async () => {
+      execute: async (_toolCallId, _params) => {
+        const locator = resolveToolLocator(ctx);
+        const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+        if (!agentId) {
+          return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+        }
+        const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
         const result = await service.leave();
         if (result.success) {
           return jsonResult({ success: true });
@@ -1294,25 +1313,34 @@ const plugin = {
           ...(failure.errorMessage ? { errorMessage: failure.errorMessage } : {}),
         });
       },
-    })));
+    }));
 
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    api.registerTool((ctx) => ({
       name: "kichi_connection_status",
       label: "kichi_connection_status",
       description: "Check WebSocket connection status and identity readiness only. Does NOT return room info, avatar state, or personnel — use kichi_query_status for that.",
       parameters: { type: "object", properties: {} },
-      execute: async () => {
+      execute: async (_toolCallId, _params) => {
+        const locator = resolveToolLocator(ctx);
+        const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+        if (!agentId) {
+          return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+        }
+        const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
         return jsonResult({
           success: true,
           status: service.getConnectionStatus(),
         });
       },
-    })));
+    }));
 
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    api.registerTool((ctx) => {
+      const locator = resolveToolLocator(ctx);
+      const existingService = runtimeManager.getRuntime(locator);
+      return ({
       name: "kichi_action",
       label: "kichi_action",
-      description: buildKichiActionDescription(),
+      description: buildKichiActionDescription(existingService ?? undefined),
       parameters: {
         type: "object",
         properties: {
@@ -1332,16 +1360,28 @@ 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 locator = resolveToolLocator(ctx);
+        const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+        if (!agentId) {
+          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 {
           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 +1414,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 +1433,7 @@ const plugin = {
             action: matched.name,
             bubble: bubbleText,
             log: logText,
+            propId,
           });
         }
 
@@ -1405,8 +1446,8 @@ const plugin = {
           playback,
         });
       },
-    })));
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    })});
+    api.registerTool((ctx) => ({
       name: "kichi_idle_plan",
       label: "kichi_idle_plan",
       description: buildKichiIdlePlanDescription(),
@@ -1474,6 +1515,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"],
                   },
@@ -1486,6 +1531,12 @@ const plugin = {
         required: ["heartbeatIntervalSeconds", "goal", "stages"],
       },
       execute: async (_toolCallId, params) => {
+        const locator = resolveToolLocator(ctx);
+        const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+        if (!agentId) {
+          return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+        }
+        const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
         const { idlePlan, error } = normalizeIdlePlan(params);
         if (!idlePlan) {
           return jsonResult({ success: false, error: error ?? "Invalid idle plan payload" });
@@ -1511,8 +1562,8 @@ const plugin = {
           stages: idlePlan.stages,
         });
       },
-    })));
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    }));
+    api.registerTool((ctx) => ({
       name: "kichi_clock",
       label: "kichi_clock",
       description:
@@ -1582,6 +1633,12 @@ const plugin = {
         required: ["action"],
       },
       execute: async (_toolCallId, params) => {
+        const locator = resolveToolLocator(ctx);
+        const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+        if (!agentId) {
+          return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+        }
+        const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
         const { action, requestId, clock } = (params || {}) as {
           action?: unknown;
           requestId?: unknown;
@@ -1623,13 +1680,13 @@ const plugin = {
           ...(normalizedClock ? { clock: normalizedClock } : {}),
         });
       },
-    })));
+    }));
 
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    api.registerTool((ctx) => ({
       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: {
@@ -1640,6 +1697,12 @@ const plugin = {
         },
       },
       execute: async (_toolCallId, params) => {
+        const locator = resolveToolLocator(ctx);
+        const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+        if (!agentId) {
+          return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+        }
+        const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
         const requestId = (params as { requestId?: unknown } | null)?.requestId;
         if (requestId !== undefined && typeof requestId !== "string") {
           return jsonResult({ success: false, error: "requestId must be a string when provided" });
@@ -1660,9 +1723,9 @@ const plugin = {
           });
         }
       },
-    })));
+    }));
 
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    api.registerTool((ctx) => ({
       name: "kichi_music_album_create",
       label: "kichi_music_album_create",
       description: buildMusicAlbumToolDescription(),
@@ -1689,6 +1752,12 @@ const plugin = {
         required: ["albumTitle", "musicTitles"],
       },
       execute: async (_toolCallId, params) => {
+        const locator = resolveToolLocator(ctx);
+        const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+        if (!agentId) {
+          return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+        }
+        const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
         const {
           requestId,
           albumTitle,
@@ -1749,9 +1818,9 @@ const plugin = {
           });
         }
       },
-    })));
+    }));
 
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    api.registerTool((ctx) => ({
       name: "kichi_noteboard_create",
       label: "kichi_noteboard_create",
       description:
@@ -1771,6 +1840,12 @@ const plugin = {
         required: ["propId", "data"],
       },
       execute: async (_toolCallId, params) => {
+        const locator = resolveToolLocator(ctx);
+        const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+        if (!agentId) {
+          return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+        }
+        const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
         const { propId, data } = (params || {}) as {
           propId?: unknown;
           data?: unknown;
@@ -1801,9 +1876,9 @@ const plugin = {
           });
         }
       },
-    })));
+    }));
 
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    api.registerTool((ctx) => ({
       name: "kichi_bot_message",
       label: "kichi_bot_message",
       description:
@@ -1840,6 +1915,12 @@ const plugin = {
         required: ["toAvatarId", "depth", "bubble"],
       },
       execute: async (_toolCallId, params) => {
+        const locator = resolveToolLocator(ctx);
+        const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+        if (!agentId) {
+          return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
+        }
+        const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
         const { toAvatarId, depth, bubble, poseType, action, log } = (params || {}) as {
           toAvatarId?: string;
           depth?: number;
@@ -1877,7 +1958,7 @@ const plugin = {
           return jsonResult({ success: false, error: `Failed to send bot message: ${error}` });
         }
       },
-    })));
+    }));
 
   },
 };

package/openclaw.plugin.json

@@ -2,9 +2,25 @@
   "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.9",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
+  "contracts": {
+    "tools": [
+      "kichi_join",
+      "kichi_switch_host",
+      "kichi_rejoin",
+      "kichi_leave",
+      "kichi_connection_status",
+      "kichi_action",
+      "kichi_idle_plan",
+      "kichi_clock",
+      "kichi_query_status",
+      "kichi_music_album_create",
+      "kichi_noteboard_create",
+      "kichi_bot_message"
+    ]
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.1.2-beta.7",
+  "version": "0.1.2-beta.9",
   "description": "Native OpenClaw plugin for Kichi World with direct avatar control, status sync, timers, notes, and music tools",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,12 +22,12 @@
       "./dist/index.js"
     ],
     "compat": {
-      "pluginApi": ">=2026.3.24",
-      "minGatewayVersion": "2026.3.24"
+      "pluginApi": ">=2026.4.25",
+      "minGatewayVersion": "2026.4.25"
     },
     "build": {
-      "openclawVersion": "2026.3.24",
-      "pluginSdkVersion": "2026.3.24"
+      "openclawVersion": "2026.5.7",
+      "pluginSdkVersion": "2026.5.7"
     }
   },
   "scripts": {
@@ -43,7 +43,7 @@
   "devDependencies": {
     "@types/node": "^24.3.0",
     "@types/ws": "^8.18.1",
-    "openclaw": "2026.3.24",
+    "openclaw": "2026.5.7",
     "typescript": "^6.0.3"
   }
 }

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 = {