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

package/index.ts

@@ -1,10 +1,10 @@
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import type {
-  AnyAgentTool,
   OpenClawPluginApi,
-  OpenClawPluginToolContext,
 } from "openclaw/plugin-sdk";
+import type { OpenClawPluginToolContext } from "openclaw/plugin-sdk/core";
+import { agentCommandFromIngress } from "openclaw/plugin-sdk/agent-runtime";
 import { parse } from "./src/config.js";
 import { KichiRuntimeManager } from "./src/runtime-manager.js";
 import { KichiForwarderService } from "./src/service.js";
@@ -13,13 +13,22 @@ import type {
   ActionPlayback,
   ActionResult,
   Album,
+  BotMessageHistoryEntry,
+  BotMessageReceivedPayload,
   ClockAction,
   ClockConfig,
+  KichiEnvironment,
+  KichiEnvironmentsConfig,
   KichiStaticConfig,
   PomodoroPhase,
   PoseType,
 } from "./src/types.js";
 const BUNDLED_STATIC_CONFIG_PATH = new URL("./config/kichi-config.json", import.meta.url);
+
+function jsonResult(payload: unknown): { content: { type: "text"; text: string }[]; details: unknown } {
+  return { content: [{ type: "text", text: JSON.stringify(payload) }], details: payload };
+}
+const BUNDLED_ENVIRONMENTS_CONFIG_PATH = new URL("./config/environments.json", import.meta.url);
 const FIXED_HOOK_STATUSES: Record<string, ActionResult> = {
   beforePromptBuild: {
     poseType: "sit",
@@ -200,6 +209,52 @@ function loadStaticConfig(): KichiStaticConfig {
   return cachedStaticConfig;
 }
 
+const VALID_ENVIRONMENTS: KichiEnvironment[] = ["steam", "steam-playtest", "test"];
+let cachedEnvironmentsConfig: KichiEnvironmentsConfig | null = null;
+let cachedEnvironmentsConfigMtime = 0;
+
+function getEnvironmentsConfigPath(): string {
+  return fileURLToPath(BUNDLED_ENVIRONMENTS_CONFIG_PATH);
+}
+
+function loadEnvironmentsConfig(): KichiEnvironmentsConfig {
+  const configPath = getEnvironmentsConfigPath();
+  const stat = fs.statSync(configPath);
+  if (cachedEnvironmentsConfig && stat.mtimeMs === cachedEnvironmentsConfigMtime) {
+    return cachedEnvironmentsConfig;
+  }
+  const raw = JSON.parse(fs.readFileSync(configPath, "utf-8")) as unknown;
+  if (!raw || typeof raw !== "object") {
+    throw new Error("config/environments.json must be a valid object");
+  }
+  const config = raw as Record<string, unknown>;
+  for (const env of VALID_ENVIRONMENTS) {
+    if (!(env in config)) {
+      throw new Error(`config/environments.json missing environment "${env}"`);
+    }
+    const value = config[env];
+    if (value !== null && typeof value !== "string") {
+      throw new Error(`config/environments.json environment "${env}" must be a string or null`);
+    }
+  }
+  cachedEnvironmentsConfig = config as KichiEnvironmentsConfig;
+  cachedEnvironmentsConfigMtime = stat.mtimeMs;
+  return cachedEnvironmentsConfig;
+}
+
+function isKichiEnvironment(value: unknown): value is KichiEnvironment {
+  return typeof value === "string" && VALID_ENVIRONMENTS.includes(value as KichiEnvironment);
+}
+
+function resolveEnvironmentHost(environment: KichiEnvironment): { host?: string; error?: string } {
+  const config = loadEnvironmentsConfig();
+  const configuredHost = config[environment];
+  if (typeof configuredHost === "string" && configuredHost.trim()) {
+    return { host: configuredHost };
+  }
+  return { error: `environment "${environment}" has no configured host — update config/environments.json first` };
+}
+
 function sendStatusUpdate(service: KichiForwarderService, status: ActionResult): void {
   const actionDefinition = getActionDefinition(status.poseType, status.action);
   service.sendStatus(
@@ -208,6 +263,7 @@ function sendStatusUpdate(service: KichiForwarderService, status: ActionResult):
     status.bubble || status.action,
     typeof status.log === "string" ? status.log.trim() : "",
     getActionPlayback(actionDefinition),
+    status.propId,
   );
 }
 
@@ -656,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 {
@@ -703,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() } : {}),
       });
     }
 
@@ -902,18 +960,6 @@ function buildMusicAlbumToolDescription(): string {
   ].join("\n");
 }
 
-function isKichiHost(value: unknown): value is string {
-  if (typeof value !== "string") {
-    return false;
-  }
-  const trimmed = value.trim();
-  return trimmed.length > 0
-    && !trimmed.includes("://")
-    && !trimmed.includes("/")
-    && !trimmed.includes("?")
-    && !trimmed.includes("#");
-}
-
 function buildMusicTitlesDescription(): string {
   return [
     "Track names are injected into this tool schema from the static config bundled with the plugin package.",
@@ -948,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.",
@@ -959,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 {
@@ -969,12 +1028,13 @@ function buildKichiIdlePlanDescription(): string {
     "The payload must include the overall goal, heartbeat interval, stage breakdown, each stage's purpose, each stage's pomodoroPhase, action list, and bubble content.",
     "Build the plan in this order.",
     "1. Pick one concrete, time-bounded fun personal project you would genuinely choose to do on your own when nobody needs you. It must fit your personality, tastes, and established character, stay rooted in your personal interests or hobbies, and be something the available Kichi actions can express clearly.",
-    "2. Use that project as the overall goal for the full interval. Do not use a vague atmosphere, a generic productivity task, or a catch-all routine summary as the goal.",
+    "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.",
+    "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(", ")}`,
     `sit actions: ${actions.sit.map((entry) => entry.name).join(", ")}`,
@@ -997,22 +1057,12 @@ function buildKichiPrompt(): string {
     "",
     "kichi_clock: set countDown for tasks with 2+ steps or >10s work. Skip for quick one-shots.",
     "",
+    "When sending a bot message, do NOT call kichi_action separately.",
+    "",
     "User opt-out, Kichi config/test work, and explicit pose requests take priority over sync.",
   ].join("\n");
 }
 
-function createAgentScopedTool(
-  runtimeManager: KichiRuntimeManager,
-  factory: (service: KichiForwarderService, ctx: OpenClawPluginToolContext) => AnyAgentTool,
-) {
-  return (ctx: OpenClawPluginToolContext) => {
-    const service = runtimeManager.getRuntime(resolveToolLocator(ctx));
-    if (!service) {
-      throw new Error("Failed to resolve agent-scoped Kichi runtime");
-    }
-    return factory(service, ctx);
-  };
-}
 
 const GLOBAL_RUNTIME_MANAGER_KEY = "__kichi_forwarder_runtime_manager__";
 
@@ -1031,6 +1081,10 @@ function getRuntimeManager(logger: OpenClawPluginApi["logger"]): KichiRuntimeMan
   return runtimeManager;
 }
 
+const BOT_MESSAGE_MAX_DEPTH = 5;
+const BOT_MESSAGE_COOLDOWN_MS = 5_000;
+const botMessageCooldowns = new Map<string, number>();
+
 const plugin = {
   id: "kichi-forwarder",
   name: "Kichi Forwarder",
@@ -1038,9 +1092,57 @@ 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();
 
+    runtimeManager.setBotMessageHandler((service, msg) => {
+      if (msg.depth >= BOT_MESSAGE_MAX_DEPTH) {
+        api.logger.info(`[kichi:${service.getAgentId()}] bot_message depth=${msg.depth} >= max=${BOT_MESSAGE_MAX_DEPTH}, ignoring`);
+        return;
+      }
+      const now = Date.now();
+      const cooldownKey = `${service.getAgentId()}:${msg.from}`;
+      const lastReply = botMessageCooldowns.get(cooldownKey) ?? 0;
+      if (now - lastReply < BOT_MESSAGE_COOLDOWN_MS) return;
+      botMessageCooldowns.set(cooldownKey, now);
+      const sessionKey = `agent:${service.getAgentId()}:default`;
+      const history: BotMessageHistoryEntry[] = [
+        ...(msg.history ?? []),
+        { from: msg.from, fromName: msg.fromName, bubble: msg.bubble },
+      ];
+      const historyLines = history.map((h) => `${h.fromName}: "${h.bubble}"`);
+      const message = `[Bot conversation]\n${historyLines.join("\n")}\n\nReply with a short bubble (2-5 words). Do not repeat what has already been said. Just output the bubble text, nothing else.`;
+      agentCommandFromIngress({
+        message,
+        sessionKey,
+        agentId: service.getAgentId(),
+        senderIsOwner: false,
+        allowModelOverride: false,
+        deliver: false,
+      }).then((result) => {
+        const replyText = (result.payloads ?? [])
+          .map((p: { text?: string }) => p.text)
+          .filter((t): t is string => typeof t === "string" && t.trim().length > 0)
+          .join(" ")
+          .trim();
+        if (!replyText) {
+          return;
+        }
+        service.sendBotMessage(msg.from, msg.depth + 1, replyText, { history }).catch((sendErr) => {
+          api.logger.warn(`[kichi:${service.getAgentId()}] bot_message send failed: ${sendErr}`);
+        });
+      }).catch((err) => {
+        api.logger.warn(`[kichi:${service.getAgentId()}] bot_message agent run failed: ${err}`);
+      });
+    });
+
     api.registerService({
       id: "kichi-forwarder",
       start: (ctx) => {
@@ -1056,8 +1158,9 @@ 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",
       parameters: {
         type: "object",
@@ -1080,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();
@@ -1090,115 +1199,148 @@ const plugin = {
           avatarId = service.readSavedAvatarId() ?? undefined;
         }
         if (!avatarId) {
-          return { success: false, error: "No avatarId" };
+          return jsonResult({ success: false, error: "No avatarId" });
         }
         if (!botName) {
-          return { success: false, error: "No botName" };
+          return jsonResult({ success: false, error: "No botName" });
         }
         if (!bio) {
-          return { success: false, error: "No bio" };
+          return jsonResult({ success: false, error: "No bio" });
         }
         if (tagsError) {
-          return { success: false, error: tagsError };
+          return jsonResult({ success: false, error: tagsError });
         }
         const result = await service.join(avatarId, botName, bio, tags ?? []);
         if (result.success) {
-          return { success: true, authKey: result.authKey };
+          return jsonResult({ success: true, authKey: result.authKey });
         }
-        return {
+        const failure = result as { success: false; error: string; errorCode?: string; errorMessage?: string };
+        return jsonResult({
           success: false,
-          error: result.error,
-          ...(result.errorCode ? { errorCode: result.errorCode } : {}),
-          ...(result.errorMessage ? { errorMessage: result.errorMessage } : {}),
-        };
+          error: failure.error,
+          ...(failure.errorCode ? { errorCode: failure.errorCode } : {}),
+          ...(failure.errorMessage ? { errorMessage: failure.errorMessage } : {}),
+        });
       },
-    })));
+    }), { name: "kichi_join" });
 
-    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:
-        "Switch Kichi runtime host and reconnect immediately without restarting the gateway.",
+        "Switch Kichi runtime environment and reconnect immediately without restarting the gateway. Host is resolved from config/environments.json.",
       parameters: {
         type: "object",
         properties: {
-          host: {
+          environment: {
             type: "string",
-            description: "Target Kichi host, for example your.kichi.host or 127.0.0.1",
+            enum: VALID_ENVIRONMENTS,
+            description: "Target environment: steam, steam-playtest, or test",
           },
         },
-        required: ["host"],
+        required: ["environment"],
       },
       execute: async (_toolCallId, params) => {
-        const host = (params as { host?: unknown } | null)?.host;
-        if (!isKichiHost(host)) {
-          return { success: false, error: "host must be a non-empty hostname without protocol or path" };
+        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(", ")}` });
         }
 
-        const status = await service.switchHost(host.trim());
-        return {
+        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,
-          host: host.trim(),
+          environment,
+          host: resolved.host,
           status,
-        };
+        });
       },
-      });
-    });
+    }), { name: "kichi_switch_host" });
 
-    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 {
+        return jsonResult({
           success: result.accepted,
           ...result,
           status: service.getConnectionStatus(),
-        };
+        });
       },
-    })));
+    }), { name: "kichi_rejoin" });
 
-    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 { success: true };
+          return jsonResult({ success: true });
         }
-        return {
+        const failure = result as { success: false; error: string; errorCode?: string; errorMessage?: string };
+        return jsonResult({
           success: false,
-          error: result.error,
-          ...(result.errorCode ? { errorCode: result.errorCode } : {}),
-          ...(result.errorMessage ? { errorMessage: result.errorMessage } : {}),
-        };
+          error: failure.error,
+          ...(failure.errorCode ? { errorCode: failure.errorCode } : {}),
+          ...(failure.errorMessage ? { errorMessage: failure.errorMessage } : {}),
+        });
       },
-    })));
+    }), { name: "kichi_leave" });
 
-    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 () => {
-        return {
+      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(),
-        };
+        });
       },
-    })));
+    }), { name: "kichi_connection_status" });
 
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    api.registerTool((ctx) => {
+      const locator = resolveToolLocator(ctx);
+      const existingService = runtimeManager.getRuntime(locator);
+      return ({
       name: "kichi_action",
-      description: buildKichiActionDescription(),
+      label: "kichi_action",
+      description: buildKichiActionDescription(existingService ?? undefined),
       parameters: {
         type: "object",
         properties: {
@@ -1218,39 +1360,51 @@ 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 { success: false, error: "poseType and action parameters are required" };
+          return jsonResult({ success: false, error: "poseType and action parameters are required" });
         }
         if (!["stand", "sit", "lay", "floor"].includes(poseType)) {
-          return {
+          return jsonResult({
             success: false,
             error: `Invalid poseType: ${poseType}. Must be stand, sit, lay, or floor`,
-          };
+          });
         }
         if (!service.hasValidIdentity() || !service.isConnected()) {
-          return { success: false, error: "Not connected to Kichi world" };
+          return jsonResult({ success: false, error: "Not connected to Kichi world" });
         }
 
         const normalizedPoseType = poseType as PoseType;
         const poseActions = loadStaticConfig().actions[normalizedPoseType];
         const matched = poseActions.find((entry) => entry.name.toLowerCase() === action.toLowerCase());
         if (!matched) {
-          return {
+          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;
@@ -1260,15 +1414,15 @@ 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 {
+              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
@@ -1279,21 +1433,23 @@ const plugin = {
             action: matched.name,
             bubble: bubbleText,
             log: logText,
+            propId,
           });
         }
 
-        return {
+        return jsonResult({
           success: true,
           poseType: normalizedPoseType,
           action: matched.name,
           bubble: bubbleText,
           log: logText,
           playback,
-        };
+        });
       },
-    })));
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    })}, { name: "kichi_action" });
+    api.registerTool((ctx) => ({
       name: "kichi_idle_plan",
+      label: "kichi_idle_plan",
       description: buildKichiIdlePlanDescription(),
       parameters: {
         type: "object",
@@ -1359,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"],
                   },
@@ -1371,12 +1531,18 @@ 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 { success: false, error: error ?? "Invalid idle plan payload" };
+          return jsonResult({ success: false, error: error ?? "Invalid idle plan payload" });
         }
         if (!service.hasValidIdentity() || !service.isConnected()) {
-          return { success: false, error: "Not connected to Kichi world" };
+          return jsonResult({ success: false, error: "Not connected to Kichi world" });
         }
         const sent = service.sendIdlePlan({
           ...(idlePlan.requestId ? { requestId: idlePlan.requestId } : {}),
@@ -1385,20 +1551,21 @@ const plugin = {
           stages: idlePlan.stages,
         });
         if (!sent) {
-          return { success: false, error: "Failed to send idle plan payload" };
+          return jsonResult({ success: false, error: "Failed to send idle plan payload" });
         }
-        return {
+        return jsonResult({
           success: true,
           ...(idlePlan.requestId ? { requestId: idlePlan.requestId } : {}),
           heartbeatIntervalSeconds: idlePlan.heartbeatIntervalSeconds,
           totalDurationSeconds: idlePlan.totalDurationSeconds,
           goal: idlePlan.goal,
           stages: idlePlan.stages,
-        };
+        });
       },
-    })));
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    }), { name: "kichi_idle_plan" });
+    api.registerTool((ctx) => ({
       name: "kichi_clock",
+      label: "kichi_clock",
       description:
         "Send clock commands to Kichi world. Supported actions are set and stop.",
       parameters: {
@@ -1466,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;
@@ -1473,46 +1646,47 @@ const plugin = {
         };
 
         if (!isClockAction(action)) {
-          return {
+          return jsonResult({
             success: false,
             error: "action must be one of: set, stop",
-          };
+          });
         }
         if (requestId !== undefined && typeof requestId !== "string") {
-          return { success: false, error: "requestId must be a string when provided" };
+          return jsonResult({ success: false, error: "requestId must be a string when provided" });
         }
         const normalizedRequestId = typeof requestId === "string" ? requestId : undefined;
         if (!service.hasValidIdentity() || !service.isConnected()) {
-          return { success: false, error: "Not connected to Kichi world" };
+          return jsonResult({ success: false, error: "Not connected to Kichi world" });
         }
 
         let normalizedClock: ClockConfig | undefined;
         if (action === "set") {
           const { clock: nextClock, error } = normalizeClockConfig(clock);
           if (!nextClock) {
-            return { success: false, error: error ?? "Invalid clock payload" };
+            return jsonResult({ success: false, error: error ?? "Invalid clock payload" });
           }
           normalizedClock = nextClock;
         }
 
         const sent = service.sendClock(action, normalizedClock, normalizedRequestId);
         if (!sent) {
-          return { success: false, error: "Failed to send clock payload" };
+          return jsonResult({ success: false, error: "Failed to send clock payload" });
         }
 
-        return {
+        return jsonResult({
           success: true,
           action,
           requestId: normalizedRequestId,
           ...(normalizedClock ? { clock: normalizedClock } : {}),
-        };
+        });
       },
-    })));
+    }), { name: "kichi_clock" });
 
-    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: {
@@ -1523,30 +1697,37 @@ 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 { success: false, error: "requestId must be a string when provided" };
+          return jsonResult({ success: false, error: "requestId must be a string when provided" });
         }
         if (!service.hasValidIdentity() || !service.isConnected()) {
-          return { success: false, error: "Not connected to Kichi world" };
+          return jsonResult({ success: false, error: "Not connected to Kichi world" });
         }
 
         try {
           const result = await service.queryStatus(
             typeof requestId === "string" ? requestId : undefined,
           );
-          return result;
+          return jsonResult(result);
         } catch (error) {
-          return {
+          return jsonResult({
             success: false,
             error: `Failed to query status: ${error}`,
-          };
+          });
         }
       },
-    })));
+    }), { name: "kichi_query_status" });
 
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    api.registerTool((ctx) => ({
       name: "kichi_music_album_create",
+      label: "kichi_music_album_create",
       description: buildMusicAlbumToolDescription(),
       parameters: {
         type: "object",
@@ -1571,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,
@@ -1582,33 +1769,33 @@ const plugin = {
         };
 
         if (requestId !== undefined && typeof requestId !== "string") {
-          return { success: false, error: "requestId must be a string when provided" };
+          return jsonResult({ success: false, error: "requestId must be a string when provided" });
         }
         if (typeof albumTitle !== "string" || !albumTitle.trim()) {
-          return { success: false, error: "albumTitle is required" };
+          return jsonResult({ success: false, error: "albumTitle is required" });
         }
         if (!Array.isArray(musicTitles)) {
-          return { success: false, error: "musicTitles must be an array of track names" };
+          return jsonResult({ success: false, error: "musicTitles must be an array of track names" });
         }
 
         const { titles: normalizedTitles, invalidTitles } = normalizeMusicTitles(musicTitles);
         if (normalizedTitles.length === 0) {
-          return {
+          return jsonResult({
             success: false,
             error: "musicTitles must contain at least one valid track name from the static config bundled with the plugin package",
             examples: getMusicTitleExamples(),
-          };
+          });
         }
         if (invalidTitles.length > 0) {
-          return {
+          return jsonResult({
             success: false,
             error: `Unknown musicTitles: ${invalidTitles.join(", ")}`,
             hint: "Use exact track names from the static config bundled with the plugin package",
             examples: getMusicTitleExamples(),
-          };
+          });
         }
         if (!service.hasValidIdentity() || !service.isConnected()) {
-          return { success: false, error: "Not connected to Kichi world" };
+          return jsonResult({ success: false, error: "Not connected to Kichi world" });
         }
 
         try {
@@ -1617,24 +1804,25 @@ const plugin = {
             normalizedTitles,
             typeof requestId === "string" ? requestId : undefined,
           );
-          return {
+          return jsonResult({
             success: true,
             requestId: normalizedRequestId,
             albumTitle: albumTitle.trim(),
             musicTitles: normalizedTitles,
             trackCount: normalizedTitles.length,
-          };
+          });
         } catch (error) {
-          return {
+          return jsonResult({
             success: false,
             error: `Failed to create music album: ${error}`,
-          };
+          });
         }
       },
-    })));
+    }), { name: "kichi_music_album_create" });
 
-    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.",
       parameters: {
@@ -1652,37 +1840,125 @@ 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;
         };
         if (typeof propId !== "string" || !propId.trim()) {
-          return { success: false, error: "propId is required" };
+          return jsonResult({ success: false, error: "propId is required" });
         }
         if (typeof data !== "string" || !data.trim()) {
-          return { success: false, error: "data is required" };
+          return jsonResult({ success: false, error: "data is required" });
         }
         if (data.trim().length > MAX_NOTEBOARD_TEXT_LENGTH) {
-          return {
+          return jsonResult({
             success: false,
             error: `data must be ${MAX_NOTEBOARD_TEXT_LENGTH} characters or fewer`,
-          };
+          });
         }
         if (!service.hasValidIdentity() || !service.isConnected()) {
-          return { success: false, error: "Not connected to Kichi world" };
+          return jsonResult({ success: false, error: "Not connected to Kichi world" });
         }
 
         try {
           service.createNotesBoardNote(propId.trim(), data.trim());
-          return { success: true };
+          return jsonResult({ success: true });
         } catch (error) {
-          return {
+          return jsonResult({
             success: false,
             error: `Failed to create note: ${error}`,
-          };
+          });
+        }
+      },
+    }), { name: "kichi_noteboard_create" });
+
+    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.",
+      parameters: {
+        type: "object",
+        properties: {
+          toAvatarId: {
+            type: "string",
+            description: "Target bot's avatarId (resolve via kichi_query_status if unknown). Use \"*\" only for broadcasting to all bots.",
+          },
+          depth: {
+            type: "number",
+            description: "Conversation depth counter. Increment from the received message's depth.",
+          },
+          bubble: {
+            type: "string",
+            description: "The message to send (2-5 words, visible to everyone). Must not repeat previous messages.",
+          },
+          poseType: {
+            type: "string",
+            enum: ["stand", "sit", "lay", "floor"],
+            description: "Optional pose change when sending.",
+          },
+          action: {
+            type: "string",
+            description: "Optional action to perform when sending.",
+          },
+          log: {
+            type: "string",
+            description: "Optional activity log entry.",
+          },
+        },
+        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;
+          bubble?: string;
+          poseType?: PoseType;
+          action?: string;
+          log?: string;
+        };
+        if (typeof toAvatarId !== "string" || !toAvatarId.trim()) {
+          return jsonResult({ success: false, error: "toAvatarId is required" });
+        }
+        if (typeof depth !== "number" || depth < 0) {
+          return jsonResult({ success: false, error: "depth must be a non-negative number" });
+        }
+        if (typeof bubble !== "string" || !bubble.trim()) {
+          return jsonResult({ success: false, error: "bubble is required" });
+        }
+        if (!service.hasValidIdentity() || !service.isConnected()) {
+          return jsonResult({ success: false, error: "Not connected to Kichi world" });
+        }
+        try {
+          let playback: ActionPlayback | undefined;
+          if (poseType && action) {
+            const actionDef = getActionDefinition(poseType, action);
+            playback = getActionPlayback(actionDef);
+          }
+          const ack = await service.sendBotMessage(toAvatarId.trim(), depth, bubble.trim(), {
+            poseType,
+            action: action?.trim(),
+            log: log?.trim(),
+            playback,
+          });
+          return jsonResult({ success: true, ...ack });
+        } catch (error) {
+          return jsonResult({ success: false, error: `Failed to send bot message: ${error}` });
         }
       },
-    })));
+    }), { name: "kichi_bot_message" });
 
   },
 };