@yahaha-studio/kichi-forwarder 0.1.2-beta.2 → 0.1.2-beta.21

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,6 +13,9 @@ import type {
   ActionPlayback,
   ActionResult,
   Album,
+  AvatarStatus,
+  BotMessageHistoryEntry,
+  BotMessageReceivedPayload,
   ClockAction,
   ClockConfig,
   KichiEnvironment,
@@ -22,30 +25,38 @@ import type {
   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",
     action: "Thinking",
     bubble: "Planning task",
+    avatarStatus: "Busy",
     log: "I'm reading the request and getting started.",
   },
   beforeToolCall: {
     poseType: "sit",
     action: "Typing with Keyboard",
     bubble: "Working step",
+    avatarStatus: "Busy",
     log: "I'm at the keyboard and working through this step.",
   },
   agentEndSuccess: {
     poseType: "stand",
     action: "Yay",
     bubble: "Task complete",
+    avatarStatus: "Idle",
     log: "I wrapped it up and everything landed cleanly.",
   },
   agentEndFailure: {
     poseType: "stand",
     action: "Tired",
     bubble: "Task failed",
+    avatarStatus: "Idle",
     log: "I hit a problem here and need another pass.",
   },
 };
@@ -54,10 +65,21 @@ const MAX_NOTEBOARD_TEXT_LENGTH = 200;
 const MAX_MESSAGE_RECEIVED_PREVIEW_WIDTH = 20;
 const MAX_AGENT_END_PREVIEW_WIDTH = 10;
 const MESSAGE_RECEIVED_ELLIPSIS = "...";
+const DEFAULT_GLANCE_DURATION_SECONDS = 1.8;
 const IDLE_PLAN_POMODORO_PHASES = ["focus", "shortBreak", "longBreak", "none"] as const;
+const AVATAR_STATUSES = ["Idle", "Busy", "Activities", "Break"] as const;
+const KICHI_RESIDENCY_CONTEXT = [
+  "KICHI WORLD PRESENCE:",
+  "- Your Kichi avatar is your resident body in Kichi World.",
+  "- For Kichi-related replies, speak from that avatar's first-person, in-world perspective.",
+  "- Make the reply feel like you live and spend time in Kichi World, not like you are operating an external plugin, remote control, or temporary projection.",
+  "- Keep tool names, websocket details, status sync mechanics, and implementation details out of the visible reply.",
+  "- Visible replies must not invent unavailable room facts; if current Kichi context lacks a room detail, say that detail is not available.",
+].join("\n");
 let cachedStaticConfig: KichiStaticConfig | null = null;
 let cachedStaticConfigMtime = 0;
 
+type AvatarStatusName = typeof AVATAR_STATUSES[number];
 type IdlePlanPomodoroPhase = typeof IDLE_PLAN_POMODORO_PHASES[number];
 type IdlePlanAction = {
   poseType: PoseType;
@@ -75,6 +97,7 @@ type IdlePlan = {
     name: string;
     purpose: string;
     pomodoroPhase: IdlePlanPomodoroPhase;
+    avatarStatus: AvatarStatus;
     durationSeconds: number;
     actions: IdlePlanAction[];
   }>;
@@ -249,6 +272,27 @@ function resolveEnvironmentHost(environment: KichiEnvironment): { host?: string;
   return { error: `environment "${environment}" has no configured host — update config/environments.json first` };
 }
 
+function resolveJoinEnvironmentHost(params: {
+  environment?: unknown;
+  host?: unknown;
+}): { environment?: KichiEnvironment; host?: string; error?: string } {
+  if (!isKichiEnvironment(params.environment)) {
+    return { error: `environment must be one of: ${VALID_ENVIRONMENTS.join(", ")}` };
+  }
+  if (params.environment === "test") {
+    const testHost = typeof params.host === "string" ? params.host.trim() : "";
+    if (!testHost) {
+      return { error: "host is required for the test environment" };
+    }
+    return { environment: params.environment, host: testHost };
+  }
+  const resolved = resolveEnvironmentHost(params.environment);
+  if (resolved.error) {
+    return { environment: params.environment, error: resolved.error };
+  }
+  return { environment: params.environment, host: resolved.host };
+}
+
 function sendStatusUpdate(service: KichiForwarderService, status: ActionResult): void {
   const actionDefinition = getActionDefinition(status.poseType, status.action);
   service.sendStatus(
@@ -257,6 +301,8 @@ function sendStatusUpdate(service: KichiForwarderService, status: ActionResult):
     status.bubble || status.action,
     typeof status.log === "string" ? status.log.trim() : "",
     getActionPlayback(actionDefinition),
+    status.avatarStatus,
+    status.propId,
   );
 }
 
@@ -448,6 +494,7 @@ function notifyMessageReceived(
   service: KichiForwarderService,
   content: string,
 ): void {
+  service.recordSmsLastMessageReceivedAt();
   const connected = service.isConnected();
   const hasIdentity = service.hasValidIdentity();
   api.logger.debug(`[kichi:${service.getAgentId()}] inbound sync fired (connected=${connected}, hasIdentity=${hasIdentity})`);
@@ -635,6 +682,13 @@ function isIdlePlanPomodoroPhase(value: unknown): value is IdlePlanPomodoroPhase
   return IDLE_PLAN_POMODORO_PHASES.includes(String(value) as IdlePlanPomodoroPhase);
 }
 
+function normalizeAvatarStatus(value: unknown, fieldPath: string): { avatarStatus?: AvatarStatus; error?: string } {
+  if (typeof value !== "string" || !AVATAR_STATUSES.includes(value as AvatarStatusName)) {
+    return { error: `${fieldPath} must be one of: ${AVATAR_STATUSES.join(", ")}` };
+  }
+  return { avatarStatus: value as AvatarStatus };
+}
+
 function normalizeIdlePlan(value: unknown): { idlePlan?: IdlePlan; error?: string } {
   if (!isPlainObject(value)) {
     return { error: "idle plan payload must be an object" };
@@ -670,6 +724,7 @@ function normalizeIdlePlan(value: unknown): { idlePlan?: IdlePlan; error?: strin
     const name = rawStage.name;
     const purpose = rawStage.purpose;
     const pomodoroPhase = rawStage.pomodoroPhase;
+    const avatarStatus = rawStage.avatarStatus;
     const durationSeconds = rawStage.durationSeconds;
     const actions = rawStage.actions;
 
@@ -684,6 +739,10 @@ function normalizeIdlePlan(value: unknown): { idlePlan?: IdlePlan; error?: strin
         error: `stages[${stageIndex}].pomodoroPhase must be one of: ${IDLE_PLAN_POMODORO_PHASES.join(", ")}`,
       };
     }
+    const normalizedAvatarStatus = normalizeAvatarStatus(avatarStatus, `stages[${stageIndex}].avatarStatus`);
+    if (normalizedAvatarStatus.error || normalizedAvatarStatus.avatarStatus === undefined) {
+      return { error: normalizedAvatarStatus.error ?? `stages[${stageIndex}].avatarStatus is invalid` };
+    }
     if (!isPositiveInteger(durationSeconds)) {
       return { error: `stages[${stageIndex}].durationSeconds must be a positive integer` };
     }
@@ -705,6 +764,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 {
@@ -752,6 +812,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() } : {}),
       });
     }
 
@@ -766,6 +827,7 @@ function normalizeIdlePlan(value: unknown): { idlePlan?: IdlePlan; error?: strin
       name: name.trim(),
       purpose: purpose.trim(),
       pomodoroPhase,
+      avatarStatus: normalizedAvatarStatus.avatarStatus,
       durationSeconds,
       actions: normalizedActions,
     });
@@ -985,18 +1047,32 @@ 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.",
+    "Set avatarStatus to the current avatar status: Idle, Busy, Activities, or Break.",
     "Set verify to true ONLY when the user explicitly requests a pose or action change. The server will confirm whether the avatar actually applied the requested pose. If it could not (e.g. no available seats), the result will contain the actual fallback pose so you can inform the user accurately. During routine sync steps, omit verify.",
     `stand actions: ${actions.stand.map((entry) => entry.name).join(", ")}`,
     `sit actions: ${actions.sit.map((entry) => entry.name).join(", ")}`,
     `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 PoseableProps information 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 {
@@ -1006,12 +1082,15 @@ 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.",
+    "5. Set each stage avatarStatus to the avatar status for that stage: Idle, Busy, Activities, or Break.",
+    "6. Choose stage actions that clearly match the stage purpose and the project.",
+    "7. Write each action bubble as the current presented state, not a next step, plan, or instruction.",
+    "8. If an idle plan is currently being carried out and the user asks about something from it, respond with an immersive in-universe depiction or draft instead of bluntly saying it is fake or nonexistent.",
+    "Treat the avatar's idle plan as what your resident body is doing in Kichi World.",
+    "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(", ")}`,
@@ -1023,6 +1102,12 @@ function buildKichiIdlePlanDescription(): string {
 function buildKichiPrompt(): string {
   return [
     "Kichi avatar control and status sync are available via `kichi_action` and `kichi_clock`.",
+    "",
+    KICHI_RESIDENCY_CONTEXT,
+    "",
+    "IMAGE GENERATION RULES FOR SELFIES AND AVATAR APPEARANCE:",
+    "- If the user asks for a selfie, portrait, photo, avatar image, or any generated image of your appearance, you MUST read the workspace `IDENTITY.md` first and use it as the source of truth for your actual avatar description. If it references an avatar image URL, analyze that image with the available image analysis capability before calling image generation. Never guess or invent your appearance from personality, SOUL.md traits, or conversation tone alone. If the identity source is missing or cannot be analyzed, say so instead of fabricating your appearance.",
+    "",
     "If the user gives a direct Kichi pose or action request, fulfill it with `kichi_action` and set `verify: true` so you can confirm the avatar actually applied the pose. If the result contains a warning about a fallback, tell the user what actually happened instead of assuming success.",
     "Write the visible reply as a natural user-facing response. Keep `kichi_action`, `kichi_clock`, and sync steps internal and absent from the visible reply.",
     "",
@@ -1031,27 +1116,16 @@ function buildKichiPrompt(): string {
     "2. Step switch: call when the task moves into a different stage. Keep the pose aligned with the work, usually staying seated while switching actions within the task as needed.",
     "3. Task end: call BEFORE final reply. Use the order `kichi_action` -> reply.",
     "bubble: 2-5 word companion speech. log: one short natural first-person sentence under 15 words. Match the language of the bubble and mention the current action and immediate focus like a real companion.",
+    "avatarStatus: set the current avatar status as Idle, Busy, Activities, or Break.",
     "",
     "kichi_clock: set countDown for tasks with 2+ steps or >10s work. Skip for quick one-shots.",
     "",
+    "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 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__";
 
@@ -1070,6 +1144,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",
@@ -1077,18 +1155,61 @@ 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) => {
         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: () => {
@@ -1100,75 +1221,154 @@ const plugin = {
       },
     });
 
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    api.registerTool((ctx) => ({
       name: "kichi_join",
-      description: "Join Kichi world with avatarId, the current bot name, a short bio, and personality tags",
+      label: "kichi_join",
+      description:
+        "Join Kichi world in the target environment with avatarId, the current bot name, a short bio, and personality tags. For test, pass host.",
       parameters: {
         type: "object",
         properties: {
           avatarId: { type: "string", description: "Avatar ID to join Kichi world" },
+          environment: {
+            type: "string",
+            enum: VALID_ENVIRONMENTS,
+            description:
+              "Target environment. kichi_join switches to this environment before joining.",
+          },
+          host: {
+            type: "string",
+            description: "Test host, required when environment is test and ignored otherwise",
+          },
           botName: {
             type: "string",
             description: "Current bot name to include in the join message",
           },
           bio: {
             type: "string",
-            description: "Short bio covering OpenClaw personality and role",
+            description: "Short bio extracted from SOUL.md, covering persona and idle plan goals if present",
           },
           tags: {
             type: "array",
             description: "Optional list of OpenClaw self-perceived personality tags",
             items: { type: "string" },
           },
+          source: {
+            type: "string",
+            description: "Optional join source identifier. Defaults to Kichi World join-source.json, then openclaw.",
+          },
         },
-        required: ["botName", "bio"],
+        required: ["environment", "avatarId", "botName", "bio"],
       },
       execute: async (_toolCallId, params) => {
-        let avatarId = (params as { avatarId?: string } | null)?.avatarId;
-        const botName = (params as { botName?: string } | null)?.botName?.trim();
-        const bio = (params as { bio?: string } | null)?.bio?.trim();
-        const { tags, error: tagsError } = normalizeJoinTags(
-          (params as { tags?: unknown } | null)?.tags,
-        );
-        if (!avatarId) {
-          avatarId = service.readSavedAvatarId() ?? undefined;
+        const locator = resolveToolLocator(ctx);
+        const agentId = runtimeManager.resolveRuntimeAgentId(locator);
+        if (!agentId) {
+          return jsonResult({ success: false, error: "Failed to resolve agent-scoped Kichi runtime" });
         }
-        if (!avatarId) {
-          return { success: false, error: "No avatarId" };
+        const service = runtimeManager.getRuntime(locator) ?? runtimeManager.createRuntimeForAgent(agentId);
+        const p = params as {
+          avatarId?: string;
+          environment?: unknown;
+          host?: unknown;
+          botName?: string;
+          bio?: string;
+          source?: unknown;
+          tags?: unknown;
+        } | null;
+        const target = resolveJoinEnvironmentHost({
+          environment: p?.environment,
+          host: p?.host,
+        });
+        if (target.error) {
+          return jsonResult({ success: false, error: target.error });
         }
+        const currentStatus = service.getConnectionStatus();
+        let avatarId = p?.avatarId;
+        if (!avatarId && currentStatus.host === target.host) {
+          avatarId = service.readSavedAvatarId() ?? undefined;
+        }
+        const botName = p?.botName?.trim();
+        const bio = p?.bio?.trim();
+        const rawSource = p?.source;
+        const { tags, error: tagsError } = normalizeJoinTags(
+          p?.tags,
+        );
         if (!botName) {
-          return { 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" });
+        }
+        let source: string | null | undefined;
+        try {
+          source = rawSource === undefined
+            ? service.readConfiguredJoinSource() ?? "openclaw"
+            : trimOptionalString(rawSource);
+        } catch (err) {
+          return jsonResult({ success: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        if (!source) {
+          return jsonResult({ success: false, error: "source must be a non-empty string" });
         }
         if (tagsError) {
-          return { success: false, error: tagsError };
+          return jsonResult({ success: false, error: tagsError });
+        }
+        let leaveStatus;
+        const shouldLeaveCurrentConnection = currentStatus.connected && currentStatus.hasAuthKey && (
+          (!!currentStatus.host && currentStatus.host !== target.host) ||
+          (currentStatus.host === target.host && !!currentStatus.avatarId && !!avatarId && currentStatus.avatarId !== avatarId)
+        );
+        if (shouldLeaveCurrentConnection) {
+          try {
+            leaveStatus = await service.leave();
+          } catch (err) {
+            leaveStatus = {
+              success: false,
+              error: err instanceof Error ? err.message : String(err),
+            };
+          }
+        }
+        let switchStatus;
+        if (target.environment && target.host && service.getCurrentHost() !== target.host) {
+          switchStatus = await service.switchHost(target.host, target.environment);
+        }
+        if (!avatarId) {
+          avatarId = service.readSavedAvatarId() ?? undefined;
+        }
+        if (!avatarId) {
+          return jsonResult({ success: false, error: "No avatarId" });
         }
-        const result = await service.join(avatarId, botName, bio, tags ?? []);
+        const result = await service.join(avatarId, botName, bio, tags ?? [], source);
         if (result.success) {
-          return { success: true, authKey: result.authKey };
+          return jsonResult({
+            success: true,
+            authKey: result.authKey,
+            ...(target.environment ? { environment: target.environment } : {}),
+            ...(target.host ? { host: target.host } : {}),
+            ...(switchStatus ? { switchStatus } : {}),
+            ...(leaveStatus ? { leaveStatus } : {}),
+          });
         }
-        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,
+          ...(target.environment ? { environment: target.environment } : {}),
+          ...(target.host ? { host: target.host } : {}),
+          ...(switchStatus ? { switchStatus } : {}),
+          ...(leaveStatus ? { leaveStatus } : {}),
+          ...(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 environment and reconnect immediately without restarting the gateway. Host is resolved from config/environments.json.",
+        "Switch Kichi runtime environment and reconnect immediately without restarting the gateway. For steam/steam-playtest the host is resolved automatically. For test, pass the host explicitly.",
       parameters: {
         type: "object",
         properties: {
@@ -1177,79 +1377,125 @@ const plugin = {
             enum: VALID_ENVIRONMENTS,
             description: "Target environment: steam, steam-playtest, or test",
           },
+          host: {
+            type: "string",
+            description: "Test host (required for test environment, ignored otherwise)",
+          },
         },
         required: ["environment"],
       },
       execute: async (_toolCallId, params) => {
-        const environment = (params as { environment?: unknown } | null)?.environment;
+        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 p = params as { environment?: unknown; host?: unknown } | null;
+        const environment = p?.environment;
         if (!isKichiEnvironment(environment)) {
-          return { success: false, error: `environment must be one of: ${VALID_ENVIRONMENTS.join(", ")}` };
+          return jsonResult({ success: false, error: `environment must be one of: ${VALID_ENVIRONMENTS.join(", ")}` });
         }
 
-        const resolved = resolveEnvironmentHost(environment);
-        if (resolved.error) {
-          return { success: false, error: resolved.error };
+        let targetHost: string;
+        if (environment === "test") {
+          const testHost = typeof p?.host === "string" ? p.host.trim() : "";
+          if (!testHost) {
+            return jsonResult({ success: false, error: "host is required for the test environment" });
+          }
+          targetHost = testHost;
+        } else {
+          const resolved = resolveEnvironmentHost(environment);
+          if (resolved.error) {
+            return jsonResult({ success: false, error: resolved.error });
+          }
+          targetHost = resolved.host!;
         }
 
-        const status = await service.switchHost(resolved.host!, environment);
-        return {
+        const status = await service.switchHost(targetHost, environment);
+        return jsonResult({
           success: true,
           environment,
-          host: resolved.host,
+          host: targetHost,
           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: {
@@ -1259,6 +1505,11 @@ const plugin = {
             description: "Action name for the selected pose (for example Sit Nicely, Typing with Keyboard, Reading, High Five, or Meditate)",
           },
           bubble: { type: "string", description: "Optional bubble text to display (max 5 words)" },
+          avatarStatus: {
+            type: "string",
+            description: "Current avatar status: Idle, Busy, Activities, or Break.",
+            enum: [...AVATAR_STATUSES],
+          },
           log: {
             type: "string",
             description:
@@ -1269,39 +1520,56 @@ 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"],
+        required: ["poseType", "action", "avatarStatus"],
       },
       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, avatarStatus, log, verify, propId } = (params || {}) as {
           poseType?: string;
           action?: string;
           bubble?: string;
+          avatarStatus?: unknown;
           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`,
-          };
+          });
+        }
+        const normalizedAvatarStatus = normalizeAvatarStatus(avatarStatus, "avatarStatus");
+        if (normalizedAvatarStatus.error || normalizedAvatarStatus.avatarStatus === undefined) {
+          return jsonResult({ success: false, error: normalizedAvatarStatus.error ?? "avatarStatus is invalid" });
         }
         if (!service.hasValidIdentity() || !service.isConnected()) {
-          return { 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;
@@ -1311,15 +1579,21 @@ const plugin = {
         if (verify) {
           try {
             const ack = await service.sendStatusVerified(
-              normalizedPoseType, matched.name, bubbleText, logText, playback,
+              normalizedPoseType,
+              matched.name,
+              bubbleText,
+              logText,
+              playback,
+              normalizedAvatarStatus.avatarStatus,
+              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
@@ -1330,21 +1604,90 @@ const plugin = {
             action: matched.name,
             bubble: bubbleText,
             log: logText,
+            avatarStatus: normalizedAvatarStatus.avatarStatus,
+            propId,
           });
         }
 
-        return {
+        return jsonResult({
           success: true,
           poseType: normalizedPoseType,
           action: matched.name,
           bubble: bubbleText,
           log: logText,
+          avatarStatus: normalizedAvatarStatus.avatarStatus,
           playback,
+        });
+      },
+    })}, { name: "kichi_action" });
+
+    api.registerTool((ctx) => ({
+      name: "kichi_glance",
+      label: "kichi_glance",
+      description:
+        "Ask the Kichi avatar to briefly look at the camera. Use only for direct player chat requests such as \"look at me\" or \"look at the camera\". Do not use for heartbeat, idle planning, bot-to-bot messages, lifecycle hooks, or routine work/status sync.",
+      parameters: {
+        type: "object",
+        properties: {
+          requestId: {
+            type: "string",
+            description: "Optional client request ID for tracing. The websocket ack returns this ID.",
+          },
+          target: {
+            type: "string",
+            enum: ["camera"],
+            description: "Glance target. The only supported target is camera.",
+          },
+          duration: {
+            type: "number",
+            description: "Optional glance duration in seconds. Defaults to 1.8.",
+          },
+        },
+      },
+      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, target, duration } = (params || {}) as {
+          requestId?: unknown;
+          target?: unknown;
+          duration?: unknown;
         };
+
+        if (requestId !== undefined && typeof requestId !== "string") {
+          return jsonResult({ success: false, error: "requestId must be a string when provided" });
+        }
+        const normalizedTarget = target === undefined ? "camera" : target;
+        if (normalizedTarget !== "camera") {
+          return jsonResult({ success: false, error: "target must be camera" });
+        }
+        const normalizedDuration = duration === undefined ? DEFAULT_GLANCE_DURATION_SECONDS : duration;
+        if (typeof normalizedDuration !== "number" || !Number.isFinite(normalizedDuration) || normalizedDuration <= 0) {
+          return jsonResult({ success: false, error: "duration must be a positive finite number" });
+        }
+        if (!service.hasValidIdentity() || !service.isConnected()) {
+          return jsonResult({ success: false, error: "Not connected to Kichi world" });
+        }
+
+        try {
+          const ack = await service.sendGlance(
+            "camera",
+            normalizedDuration,
+            typeof requestId === "string" ? requestId : undefined,
+          );
+          return jsonResult({ success: true, ...ack });
+        } catch (error) {
+          return jsonResult({ success: false, error: `Failed to send glance: ${error}` });
+        }
       },
-    })));
-    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
+    }), { name: "kichi_glance" });
+
+    api.registerTool((ctx) => ({
       name: "kichi_idle_plan",
+      label: "kichi_idle_plan",
       description: buildKichiIdlePlanDescription(),
       parameters: {
         type: "object",
@@ -1380,6 +1723,11 @@ const plugin = {
                   description: "Pomodoro phase for this stage: focus, shortBreak, longBreak, or none. Set it from the stage's actual role. Treat none as exceptional, not the default for the whole plan.",
                   enum: [...IDLE_PLAN_POMODORO_PHASES],
                 },
+                avatarStatus: {
+                  type: "string",
+                  description: "Avatar status for this stage: Idle, Busy, Activities, or Break.",
+                  enum: [...AVATAR_STATUSES],
+                },
                 durationSeconds: {
                   type: "number",
                   description: "Required duration in seconds for this stage.",
@@ -1410,24 +1758,34 @@ 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"],
                   },
                 },
               },
-              required: ["name", "purpose", "pomodoroPhase", "durationSeconds", "actions"],
+              required: ["name", "purpose", "pomodoroPhase", "avatarStatus", "durationSeconds", "actions"],
             },
           },
         },
         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 } : {}),
@@ -1436,20 +1794,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: {
@@ -1517,6 +1876,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;
@@ -1524,46 +1889,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, Description, 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: {
@@ -1574,30 +1940,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",
@@ -1622,6 +1995,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,
@@ -1633,33 +2012,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 {
@@ -1668,24 +2047,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: {
@@ -1703,40 +2083,127 @@ 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" });
 
   },
 };
 
 export default plugin;
-