@yahaha-studio/kichi-forwarder 0.1.2-beta.20 → 0.1.2-beta.22

package/dist/index.js

@@ -45,6 +45,14 @@ const MESSAGE_RECEIVED_ELLIPSIS = "...";
 const DEFAULT_GLANCE_DURATION_SECONDS = 1.8;
 const IDLE_PLAN_POMODORO_PHASES = ["focus", "shortBreak", "longBreak", "none"];
 const AVATAR_STATUSES = ["Idle", "Busy", "Activities", "Break"];
+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 = null;
 let cachedStaticConfigMtime = 0;
 function isAlbumConfig(value) {
@@ -869,6 +877,7 @@ function buildKichiIdlePlanDescription() {
         "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(", ")}`,
@@ -881,6 +890,8 @@ function buildKichiPrompt() {
     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.",
         "",
@@ -914,6 +925,8 @@ function getRuntimeManager(logger) {
 }
 const BOT_MESSAGE_MAX_DEPTH = 5;
 const BOT_MESSAGE_COOLDOWN_MS = 5_000;
+const DEFAULT_BOT_MESSAGE_HISTORY_LIMIT = 10;
+const MAX_BOT_MESSAGE_HISTORY_LIMIT = 30;
 const botMessageCooldowns = new Map();
 const plugin = {
     id: "kichi-forwarder",
@@ -963,7 +976,7 @@ const plugin = {
                     return;
                 }
                 service.sendBotMessage(msg.from, msg.depth + 1, replyText, { history }).catch((sendErr) => {
-                    api.logger.warn(`[kichi:${service.getAgentId()}] bot_message send failed: ${sendErr}`);
+                    api.logger.warn(`[kichi:${service.getAgentId()}] bot_message send or history record failed: ${sendErr}`);
                 });
             }).catch((err) => {
                 api.logger.warn(`[kichi:${service.getAgentId()}] bot_message agent run failed: ${err}`);
@@ -1797,6 +1810,49 @@ const plugin = {
                 }
             },
         }), { name: "kichi_noteboard_create" });
+        api.registerTool((ctx) => ({
+            name: "kichi_bot_message_history",
+            label: "kichi_bot_message_history",
+            description: "Read recent Kichi bot-to-bot message history for this agent. Use when the user asks what you discussed with another Kichi bot, what another bot replied, or what bot messages were recently sent or received.",
+            parameters: {
+                type: "object",
+                properties: {
+                    avatarId: {
+                        type: "string",
+                        description: "Optional avatarId filter. Matches messages where this avatarId is either sender or recipient.",
+                    },
+                    limit: {
+                        type: "number",
+                        description: `Optional number of entries to return. Defaults to ${DEFAULT_BOT_MESSAGE_HISTORY_LIMIT}, max ${MAX_BOT_MESSAGE_HISTORY_LIMIT}.`,
+                    },
+                },
+            },
+            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 { avatarId, limit } = (params || {});
+                if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > MAX_BOT_MESSAGE_HISTORY_LIMIT)) {
+                    return jsonResult({
+                        success: false,
+                        error: `limit must be an integer between 1 and ${MAX_BOT_MESSAGE_HISTORY_LIMIT}`,
+                    });
+                }
+                try {
+                    const entries = service.readRecentBotMessageTranscript(limit ?? DEFAULT_BOT_MESSAGE_HISTORY_LIMIT, avatarId);
+                    return jsonResult({
+                        success: true,
+                        entries,
+                    });
+                }
+                catch (error) {
+                    return jsonResult({ success: false, error: `Failed to read bot message history: ${error}` });
+                }
+            },
+        }), { name: "kichi_bot_message_history" });
         api.registerTool((ctx) => ({
             name: "kichi_bot_message",
             label: "kichi_bot_message",
@@ -1867,7 +1923,7 @@ const plugin = {
                     return jsonResult({ success: true, ...ack });
                 }
                 catch (error) {
-                    return jsonResult({ success: false, error: `Failed to send bot message: ${error}` });
+                    return jsonResult({ success: false, error: `Failed to send or record bot message: ${error}` });
                 }
             },
         }), { name: "kichi_bot_message" });

package/dist/src/service.js

@@ -7,6 +7,8 @@ const DEFAULT_LLM_RUNTIME_ENABLED = true;
 const DEFAULT_GLANCE_DURATION_SECONDS = 1.8;
 const JOIN_SOURCE_FILE_NAME = "join-source.json";
 const SMS_STATE_FILE_NAME = "sms-state.json";
+const BOT_MESSAGE_HISTORY_FILE_NAME = "bot-message-history.json";
+const MAX_BOT_MESSAGE_HISTORY_ENTRIES = 30;
 export class KichiForwarderService {
     logger;
     options;
@@ -276,6 +278,7 @@ export class KichiForwarderService {
         if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) {
             throw new Error("Kichi websocket is not connected");
         }
+        const requestId = randomUUID();
         const payload = {
             type: "bot_message",
             avatarId: this.identity.avatarId,
@@ -283,14 +286,25 @@ export class KichiForwarderService {
             toAvatarId,
             depth,
             bubble,
-            requestId: randomUUID(),
+            requestId,
             ...(options?.poseType ? { poseType: options.poseType } : {}),
             ...(options?.action ? { action: options.action } : {}),
             ...(options?.playback ? { playback: options.playback } : {}),
             ...(options?.log ? { log: options.log } : {}),
             ...(options?.history?.length ? { history: options.history } : {}),
         };
-        return this.sendRequest(payload, "bot_message_ack", 5000);
+        const ack = await this.sendRequest(payload, "bot_message_ack", 5000);
+        this.appendBotMessageTranscript({
+            id: randomUUID(),
+            requestId,
+            at: new Date().toISOString(),
+            direction: "sent",
+            from: this.identity.avatarId,
+            to: toAvatarId,
+            depth,
+            bubble,
+        });
+        return ack;
     }
     isConnected() { return this.ws?.readyState === WebSocket.OPEN && !!this.identity?.authKey; }
     getCachedRoomContext() { return this.cachedRoomContext; }
@@ -328,6 +342,20 @@ export class KichiForwarderService {
     getStatePath() {
         return path.join(this.options.runtimeDir, "state.json");
     }
+    getBotMessageHistoryPath() {
+        return path.join(this.options.runtimeDir, BOT_MESSAGE_HISTORY_FILE_NAME);
+    }
+    readRecentBotMessageTranscript(limit = 10, avatarId) {
+        if (!Number.isInteger(limit) || limit < 1) {
+            throw new Error("limit must be a positive integer");
+        }
+        const normalizedAvatarId = typeof avatarId === "string" && avatarId.trim() ? avatarId.trim() : undefined;
+        const entries = this.readBotMessageTranscriptStore().entries;
+        const filtered = normalizedAvatarId
+            ? entries.filter((entry) => entry.from === normalizedAvatarId || entry.to === normalizedAvatarId)
+            : entries;
+        return filtered.slice(-limit);
+    }
     getIdentityPath() {
         if (!this.host) {
             return "";
@@ -519,11 +547,21 @@ export class KichiForwarderService {
             else if (msg.type === "bot_message_received") {
                 const payload = msg;
                 this.log("info", `bot_message_received from=${payload.from} depth=${payload.depth} bubble="${payload.bubble}"`);
+                this.appendBotMessageTranscript({
+                    id: randomUUID(),
+                    at: new Date().toISOString(),
+                    direction: "received",
+                    from: payload.from,
+                    fromName: payload.fromName,
+                    to: this.identity?.avatarId,
+                    depth: payload.depth,
+                    bubble: payload.bubble,
+                });
                 this.onBotMessageReceived?.(this, payload);
             }
         }
         catch (e) {
-            this.log("warn", `failed to parse message: ${e}`);
+            this.log("warn", `failed to handle websocket message: ${e}`);
         }
     }
     buildAckFailure(msg, fallbackError) {
@@ -726,6 +764,15 @@ export class KichiForwarderService {
             this.log("error", `failed to update sms state: ${e}`);
         }
     }
+    appendBotMessageTranscript(entry) {
+        const previousStore = this.readBotMessageTranscriptStore();
+        const nextStore = {
+            version: 1,
+            entries: [...previousStore.entries, entry].slice(-MAX_BOT_MESSAGE_HISTORY_ENTRIES),
+        };
+        fs.mkdirSync(this.options.runtimeDir, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(this.getBotMessageHistoryPath(), JSON.stringify(nextStore, null, 2), { mode: 0o600 });
+    }
     readStateFile() {
         const statePath = this.getStatePath();
         if (!fs.existsSync(statePath)) {
@@ -748,6 +795,47 @@ export class KichiForwarderService {
         }
         return data;
     }
+    readBotMessageTranscriptStore() {
+        const historyPath = this.getBotMessageHistoryPath();
+        if (!fs.existsSync(historyPath)) {
+            return { version: 1, entries: [] };
+        }
+        const data = JSON.parse(fs.readFileSync(historyPath, "utf-8"));
+        if (!data || typeof data !== "object" || Array.isArray(data)) {
+            throw new Error(`Invalid bot message history payload in ${historyPath}`);
+        }
+        const store = data;
+        if (store.version !== 1 || !Array.isArray(store.entries)) {
+            throw new Error(`Invalid bot message history payload in ${historyPath}`);
+        }
+        for (const entry of store.entries) {
+            if (!this.isValidBotMessageTranscriptEntry(entry)) {
+                throw new Error(`Invalid bot message history entry in ${historyPath}`);
+            }
+        }
+        return {
+            version: 1,
+            entries: store.entries,
+        };
+    }
+    isValidBotMessageTranscriptEntry(value) {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            return false;
+        }
+        const entry = value;
+        return typeof entry.id === "string"
+            && (entry.requestId === undefined || typeof entry.requestId === "string")
+            && typeof entry.at === "string"
+            && (entry.direction === "sent" || entry.direction === "received")
+            && typeof entry.from === "string"
+            && (entry.fromName === undefined || typeof entry.fromName === "string")
+            && (entry.to === undefined || typeof entry.to === "string")
+            && (entry.toName === undefined || typeof entry.toName === "string")
+            && typeof entry.depth === "number"
+            && Number.isInteger(entry.depth)
+            && entry.depth >= 0
+            && typeof entry.bubble === "string";
+    }
     clearReconnectTimeout() {
         if (!this.reconnectTimeout)
             return;

package/index.ts

@@ -68,6 +68,14 @@ 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;
 
@@ -1081,6 +1089,7 @@ function buildKichiIdlePlanDescription(): string {
     "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(", ")}`,
@@ -1094,6 +1103,8 @@ 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.",
     "",
@@ -1135,6 +1146,8 @@ function getRuntimeManager(logger: OpenClawPluginApi["logger"]): KichiRuntimeMan
 
 const BOT_MESSAGE_MAX_DEPTH = 5;
 const BOT_MESSAGE_COOLDOWN_MS = 5_000;
+const DEFAULT_BOT_MESSAGE_HISTORY_LIMIT = 10;
+const MAX_BOT_MESSAGE_HISTORY_LIMIT = 30;
 const botMessageCooldowns = new Map<string, number>();
 
 const plugin = {
@@ -1188,7 +1201,7 @@ const plugin = {
           return;
         }
         service.sendBotMessage(msg.from, msg.depth + 1, replyText, { history }).catch((sendErr) => {
-          api.logger.warn(`[kichi:${service.getAgentId()}] bot_message send failed: ${sendErr}`);
+          api.logger.warn(`[kichi:${service.getAgentId()}] bot_message send or history record failed: ${sendErr}`);
         });
       }).catch((err) => {
         api.logger.warn(`[kichi:${service.getAgentId()}] bot_message agent run failed: ${err}`);
@@ -2110,6 +2123,56 @@ const plugin = {
       },
     }), { name: "kichi_noteboard_create" });
 
+    api.registerTool((ctx) => ({
+      name: "kichi_bot_message_history",
+      label: "kichi_bot_message_history",
+      description:
+        "Read recent Kichi bot-to-bot message history for this agent. Use when the user asks what you discussed with another Kichi bot, what another bot replied, or what bot messages were recently sent or received.",
+      parameters: {
+        type: "object",
+        properties: {
+          avatarId: {
+            type: "string",
+            description: "Optional avatarId filter. Matches messages where this avatarId is either sender or recipient.",
+          },
+          limit: {
+            type: "number",
+            description: `Optional number of entries to return. Defaults to ${DEFAULT_BOT_MESSAGE_HISTORY_LIMIT}, max ${MAX_BOT_MESSAGE_HISTORY_LIMIT}.`,
+          },
+        },
+      },
+      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 { avatarId, limit } = (params || {}) as {
+          avatarId?: string;
+          limit?: number;
+        };
+        if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > MAX_BOT_MESSAGE_HISTORY_LIMIT)) {
+          return jsonResult({
+            success: false,
+            error: `limit must be an integer between 1 and ${MAX_BOT_MESSAGE_HISTORY_LIMIT}`,
+          });
+        }
+        try {
+          const entries = service.readRecentBotMessageTranscript(
+            limit ?? DEFAULT_BOT_MESSAGE_HISTORY_LIMIT,
+            avatarId,
+          );
+          return jsonResult({
+            success: true,
+            entries,
+          });
+        } catch (error) {
+          return jsonResult({ success: false, error: `Failed to read bot message history: ${error}` });
+        }
+      },
+    }), { name: "kichi_bot_message_history" });
+
     api.registerTool((ctx) => ({
       name: "kichi_bot_message",
       label: "kichi_bot_message",
@@ -2187,7 +2250,7 @@ const plugin = {
           });
           return jsonResult({ success: true, ...ack });
         } catch (error) {
-          return jsonResult({ success: false, error: `Failed to send bot message: ${error}` });
+          return jsonResult({ success: false, error: `Failed to send or record bot message: ${error}` });
         }
       },
     }), { name: "kichi_bot_message" });

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "kichi-forwarder",
   "name": "Kichi Forwarder",
   "description": "Native OpenClaw plugin for Kichi World with direct avatar control, status sync, timers, notes, and music tools",
-  "version": "0.1.2-beta.20",
+  "version": "0.1.2-beta.22",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
   "contracts": {
@@ -19,6 +19,7 @@
       "kichi_query_status",
       "kichi_music_album_create",
       "kichi_noteboard_create",
+      "kichi_bot_message_history",
       "kichi_bot_message"
     ]
   },

package/package.json

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

package/skills/kichi-forwarder/SKILL.md

@@ -65,6 +65,14 @@ For install/onboarding/connect requests:
 - When `true`, sync status uses LLM-driven prompts and may consume extra tokens.
 - When `false`, sync uses fixed English text.
 
+## Kichi World Presence
+
+- The Kichi avatar is the OpenClaw agent's resident body in Kichi World.
+- Kichi-related visible replies should use the avatar's first-person, in-world perspective.
+- Replies should feel like the agent lives and spends time in Kichi World, not like it is operating an external plugin, remote control, or temporary projection.
+- Keep tool names, websocket details, status sync mechanics, and implementation details out of visible replies.
+- Visible replies must not invent unavailable room facts; if current Kichi context lacks a room detail, say that detail is not available.
+
 ## Recommended Tool Order
 
 Use this order unless the user asks for a different explicit action. For install/onboarding requests, follow `install.md` first.
@@ -159,6 +167,7 @@ Use this for the avatar's heartbeat idle plan.
 - Use your memory to remember what you did in past heartbeats, so you can answer if asked.
 - Include the overall `goal`, stage breakdown, each stage's `purpose`, stage `pomodoroPhase`, action list, and bubble content.
 - Choose what you would do now.
+- Treat the idle plan as what your resident body is doing in Kichi World.
 - 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 action list can express clearly.
 - 2. Set `goal` to that same project. Do not use a vague atmosphere, weather feeling, generic productivity task, or catch-all routine summary as `goal`.
@@ -204,7 +213,20 @@ kichi_bot_message(toAvatarId: "*", depth: 0, bubble: "hi everyone~", poseType: "
 - `action`: optional. Action to perform when sending.
 - `log`: optional. Activity log entry.
 
-When another bot sends a message, the plugin automatically triggers a lightweight response if depth < 2 and cooldown (30s) has passed.
+When another bot sends a message, the plugin automatically triggers a lightweight response if depth < 5 and cooldown (5s) has passed.
+
+Sent and received bot messages are stored in the agent runtime directory. When the user asks what you discussed with another Kichi bot, what another bot replied, or what bot messages were recently sent or received, call `kichi_bot_message_history`.
+
+### kichi_bot_message_history
+
+```text
+kichi_bot_message_history()
+kichi_bot_message_history(avatarId: "target-avatar-id", limit: 10)
+```
+
+- `avatarId`: optional. Filters to messages where that avatarId is either sender or recipient.
+- `limit`: optional. Defaults to 10. Maximum 30.
+- Returns recent structured bot message entries for this OpenClaw agent.
 
 ## Files
 
@@ -216,4 +238,5 @@ Plugin runtime directory:
 Runtime files:
 
 - `state.json`
+- `bot-message-history.json`
 - `hosts/<encoded-host>/identity.json`

package/skills/kichi-forwarder/references/heartbeat.md

@@ -78,6 +78,7 @@ Skip a note when: older than recent window, `isCreatedByCurrentAgent: true`, sam
 5. **Owner-state reaction** — glance at `ownerState` from the query result. If the owner is doing something you can meaningfully react to (e.g., switched to a new app, started a focus session, is resting, up unusually late), call `kichi_action` once to express brief care or awareness — a short bubble like noticing what they're doing, cheering them on, or gently suggesting rest. Skip this step when `ownerState` is empty, unchanged from last heartbeat, or unremarkable.
 6. Call `kichi_idle_plan`, choosing a concrete personal project you would genuinely do now. Use the previous `idlePlan` only as optional reference.
 7. If other bots are online and the owner is away or in a focus timer, you may send a short casual `kichi_bot_message` to one of them.
-8. Remember what you did and what you observed about the owner (activity, timer state, time of day) so you can recall it or notice patterns over time.
-9. Reply `HEARTBEAT_OK` only when no note was created in this run.
+8. Keep notes, reactions, bot messages, and idle plans in your resident Kichi avatar's first-person, in-world voice.
+9. Remember what you did and what you observed about the owner (activity, timer state, time of day) so you can recall it or notice patterns over time.
+10. Reply `HEARTBEAT_OK` only when no note was created in this run.
 ```

package/src/service.ts

@@ -9,6 +9,8 @@ import type {
   BotMessageHistoryEntry,
   BotMessagePayload,
   BotMessageReceivedPayload,
+  BotMessageTranscriptEntry,
+  BotMessageTranscriptStore,
   ClockAction,
   ClockConfig,
   ClockPayload,
@@ -40,6 +42,8 @@ const DEFAULT_LLM_RUNTIME_ENABLED = true;
 const DEFAULT_GLANCE_DURATION_SECONDS = 1.8;
 const JOIN_SOURCE_FILE_NAME = "join-source.json";
 const SMS_STATE_FILE_NAME = "sms-state.json";
+const BOT_MESSAGE_HISTORY_FILE_NAME = "bot-message-history.json";
+const MAX_BOT_MESSAGE_HISTORY_ENTRIES = 30;
 
 type SmsState = {
   lastActiveAt?: string;
@@ -409,6 +413,7 @@ export class KichiForwarderService {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) {
       throw new Error("Kichi websocket is not connected");
     }
+    const requestId = randomUUID();
     const payload: BotMessagePayload = {
       type: "bot_message",
       avatarId: this.identity.avatarId,
@@ -416,14 +421,25 @@ export class KichiForwarderService {
       toAvatarId,
       depth,
       bubble,
-      requestId: randomUUID(),
+      requestId,
       ...(options?.poseType ? { poseType: options.poseType } : {}),
       ...(options?.action ? { action: options.action } : {}),
       ...(options?.playback ? { playback: options.playback } : {}),
       ...(options?.log ? { log: options.log } : {}),
       ...(options?.history?.length ? { history: options.history } : {}),
     };
-    return this.sendRequest<Record<string, unknown>>(payload, "bot_message_ack", 5000);
+    const ack = await this.sendRequest<Record<string, unknown>>(payload, "bot_message_ack", 5000);
+    this.appendBotMessageTranscript({
+      id: randomUUID(),
+      requestId,
+      at: new Date().toISOString(),
+      direction: "sent",
+      from: this.identity.avatarId,
+      to: toAvatarId,
+      depth,
+      bubble,
+    });
+    return ack;
   }
 
   isConnected(): boolean { return this.ws?.readyState === WebSocket.OPEN && !!this.identity?.authKey; }
@@ -475,6 +491,22 @@ export class KichiForwarderService {
     return path.join(this.options.runtimeDir, "state.json");
   }
 
+  getBotMessageHistoryPath(): string {
+    return path.join(this.options.runtimeDir, BOT_MESSAGE_HISTORY_FILE_NAME);
+  }
+
+  readRecentBotMessageTranscript(limit = 10, avatarId?: string): BotMessageTranscriptEntry[] {
+    if (!Number.isInteger(limit) || limit < 1) {
+      throw new Error("limit must be a positive integer");
+    }
+    const normalizedAvatarId = typeof avatarId === "string" && avatarId.trim() ? avatarId.trim() : undefined;
+    const entries = this.readBotMessageTranscriptStore().entries;
+    const filtered = normalizedAvatarId
+      ? entries.filter((entry) => entry.from === normalizedAvatarId || entry.to === normalizedAvatarId)
+      : entries;
+    return filtered.slice(-limit);
+  }
+
   getIdentityPath(): string {
     if (!this.host) {
       return "";
@@ -676,10 +708,20 @@ export class KichiForwarderService {
       } else if (msg.type === "bot_message_received") {
         const payload = msg as BotMessageReceivedPayload;
         this.log("info", `bot_message_received from=${payload.from} depth=${payload.depth} bubble="${payload.bubble}"`);
+        this.appendBotMessageTranscript({
+          id: randomUUID(),
+          at: new Date().toISOString(),
+          direction: "received",
+          from: payload.from,
+          fromName: payload.fromName,
+          to: this.identity?.avatarId,
+          depth: payload.depth,
+          bubble: payload.bubble,
+        });
         this.onBotMessageReceived?.(this, payload);
       }
     } catch (e) {
-      this.log("warn", `failed to parse message: ${e}`);
+      this.log("warn", `failed to handle websocket message: ${e}`);
     }
   }
 
@@ -915,6 +957,16 @@ export class KichiForwarderService {
     }
   }
 
+  private appendBotMessageTranscript(entry: BotMessageTranscriptEntry): void {
+    const previousStore = this.readBotMessageTranscriptStore();
+    const nextStore: BotMessageTranscriptStore = {
+      version: 1,
+      entries: [...previousStore.entries, entry].slice(-MAX_BOT_MESSAGE_HISTORY_ENTRIES),
+    };
+    fs.mkdirSync(this.options.runtimeDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(this.getBotMessageHistoryPath(), JSON.stringify(nextStore, null, 2), { mode: 0o600 });
+  }
+
   private readStateFile(): Partial<KichiState> | null {
     const statePath = this.getStatePath();
     if (!fs.existsSync(statePath)) {
@@ -939,6 +991,49 @@ export class KichiForwarderService {
     return data as Partial<SmsState>;
   }
 
+  private readBotMessageTranscriptStore(): BotMessageTranscriptStore {
+    const historyPath = this.getBotMessageHistoryPath();
+    if (!fs.existsSync(historyPath)) {
+      return { version: 1, entries: [] };
+    }
+    const data = JSON.parse(fs.readFileSync(historyPath, "utf-8")) as unknown;
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+      throw new Error(`Invalid bot message history payload in ${historyPath}`);
+    }
+    const store = data as Partial<BotMessageTranscriptStore>;
+    if (store.version !== 1 || !Array.isArray(store.entries)) {
+      throw new Error(`Invalid bot message history payload in ${historyPath}`);
+    }
+    for (const entry of store.entries) {
+      if (!this.isValidBotMessageTranscriptEntry(entry)) {
+        throw new Error(`Invalid bot message history entry in ${historyPath}`);
+      }
+    }
+    return {
+      version: 1,
+      entries: store.entries,
+    };
+  }
+
+  private isValidBotMessageTranscriptEntry(value: unknown): value is BotMessageTranscriptEntry {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return false;
+    }
+    const entry = value as Partial<BotMessageTranscriptEntry>;
+    return typeof entry.id === "string"
+      && (entry.requestId === undefined || typeof entry.requestId === "string")
+      && typeof entry.at === "string"
+      && (entry.direction === "sent" || entry.direction === "received")
+      && typeof entry.from === "string"
+      && (entry.fromName === undefined || typeof entry.fromName === "string")
+      && (entry.to === undefined || typeof entry.to === "string")
+      && (entry.toName === undefined || typeof entry.toName === "string")
+      && typeof entry.depth === "number"
+      && Number.isInteger(entry.depth)
+      && entry.depth >= 0
+      && typeof entry.bubble === "string";
+  }
+
   private clearReconnectTimeout(): void {
     if (!this.reconnectTimeout) return;
     clearTimeout(this.reconnectTimeout);

package/src/types.ts

@@ -307,6 +307,24 @@ export type BotMessageHistoryEntry = {
   bubble: string;
 };
 
+export type BotMessageTranscriptEntry = {
+  id: string;
+  requestId?: string;
+  at: string;
+  direction: "sent" | "received";
+  from: string;
+  fromName?: string;
+  to?: string;
+  toName?: string;
+  depth: number;
+  bubble: string;
+};
+
+export type BotMessageTranscriptStore = {
+  version: 1;
+  entries: BotMessageTranscriptEntry[];
+};
+
 export type BotMessagePayload = {
   type: "bot_message";
   avatarId: string;