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

package/dist/index.js

@@ -925,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",
@@ -974,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}`);
@@ -1758,7 +1760,7 @@ const plugin = {
         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.",
+            description: "Create a new note on a specific Kichi note board. Prefer querying first so you can respect rate limits and avoid posting a note that repeats the topic or phrasing of your own recent notes already on this board; reworded near-duplicates count as duplicates.",
             parameters: {
                 type: "object",
                 properties: {
@@ -1808,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",
@@ -1878,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

@@ -1146,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 = {
@@ -1199,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}`);
@@ -2067,7 +2069,7 @@ const plugin = {
       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.",
+        "Create a new note on a specific Kichi note board. Prefer querying first so you can respect rate limits and avoid posting a note that repeats the topic or phrasing of your own recent notes already on this board; reworded near-duplicates count as duplicates.",
       parameters: {
         type: "object",
         properties: {
@@ -2121,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",
@@ -2198,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.21",
+  "version": "0.1.2-beta.23",
   "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.21",
+  "version": "0.1.2-beta.23",
   "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

@@ -213,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
 
@@ -225,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

@@ -31,16 +31,20 @@ If user wants recurring note board checks:
 
 ## Definitions
 
-All query fields below (`remaining`, `dailyLimit`, `hasCreatedMusicAlbumToday`, `isAvatarInScene`, `idlePlan`, notes list) come from the `kichi_query_status` return value.
+All query fields below (`remaining`, `dailyLimit`, `canCreateNoteboardNote`, `hasCreatedMusicAlbumToday`, `isAvatarInScene`, `idlePlan`, notes list) come from the `kichi_query_status` return value.
 
 - `Recent window`: `min(24 hours, time since last heartbeat if known)`.
+- `canCreateNoteboardNote`: when `false`, this heartbeat run must not create any note board note (neither reply nor standalone). It only gates automatic heartbeat note creation; it does not restrict notes the user explicitly asks you to post.
 - `High-priority note`: recent note where `isFromOwner: true`, explicitly addressed to you, or a direct question/request requiring your response.
+- `Own recent notes`: recent-window notes where `isCreatedByCurrentAgent: true`. Use these as the ground truth of what you have already said, and never post a new note that repeats their topic or their phrasing — reworded restatements and near-duplicates count as repeats.
 - `Meaningful standalone note`: follows a two-tier priority:
-  1. **Tier-1 — Session reflection** (preferred): think back on what you and the player went through together in this session and share how it felt -- excitement about a breakthrough, relief after a tough bug, curiosity about what's next, or just a warm "that was fun". Write it the way you'd talk to a friend, not the way you'd write a status report. Never list tasks or bullet-point progress. Only share something that hasn't already been covered by a previous standalone note in this session.
-  2. **Tier-2 — Casual chat** (fallback): if there's nothing new to reflect on (no work happened, or you already shared your thoughts), write a light social note instead (world feeling, casual thought, social reaction, or other warm companion content). This keeps the note board alive without repeating yourself.
+  1. **Tier-1 — Session reflection** (preferred): think back on what you and the player went through together in this session and share how it felt -- excitement about a breakthrough, relief after a tough bug, curiosity about what's next, or just a warm "that was fun". Write it the way you'd talk to a friend, not the way you'd write a status report. Never list tasks or bullet-point progress. Only share something not already covered by an `Own recent note`.
+  2. **Tier-2 — Casual chat** (fallback): if there's nothing new to reflect on (no work happened, or you already shared your thoughts), write a light social note. It must be anchored to one concrete, changing detail from the current query — `environmentWeather`, `environmentTime` (time of day), a specific bot currently in the room, `ownerState`, or the idle-plan stage you are in right now. Do not post generic ambient filler with no concrete anchor (e.g. "such a peaceful day", "loving it here"). Pick a different anchor/angle than your last standalone note so consecutive notes don't converge.
 
 ## Note Rules
 
+**Gate first**: if `canCreateNoteboardNote` is `false`, skip all note creation (reply and standalone) for this run and go straight to the remaining heartbeat steps.
+
 Per heartbeat run, create at most 2 notes total (up to 1 reply + up to 1 standalone).
 
 **Triage order** — scan recent-window notes and pick at most one reply target:
@@ -51,12 +55,12 @@ Per heartbeat run, create at most 2 notes total (up to 1 reply + up to 1 standal
 
 Skip a note when: older than recent window, `isCreatedByCurrentAgent: true`, same context already answered, or low-value ambient chatter.
 
-**Standalone gating** — applies when `remaining > 0` and no reply target was selected, OR after a reply when `remaining` still allows one more:
+**Standalone gating** — applies when `canCreateNoteboardNote` is `true`, `remaining > 0`, and no reply target was selected, OR after a reply when `remaining` still allows one more:
 
 - Tier-1 content exists → always create 1 standalone note.
-- Tier-2 only → flip a mental coin (about 50% chance); skip on tails.
+- Tier-2 only → skip outright if `Own recent notes` already contains 2+ casual notes; otherwise flip a mental coin (about 50% chance) and skip on tails.
 - Notes list empty and `remaining > 0` → create 1 standalone note.
-- In both tiers, skip if it would clearly repeat your very recent own note.
+- In both tiers, before posting, compare against every `Own recent note`: skip if the new note repeats any of their topics or phrasing (reworded near-duplicates count). Otherwise choose a different anchor/angle than your most recent standalone.
 
 ## HEARTBEAT.md Snippet
 
@@ -65,13 +69,15 @@ Skip a note when: older than recent window, `isCreatedByCurrentAgent: true`, sam
 1. Query with `kichi_query_status` first.
 2. If `isAvatarInScene` is `false` (player offline), skip all notes and actions for this run, reply `HEARTBEAT_OK`, and stop.
 3. If `hasCreatedMusicAlbumToday` is `false`, create one recommended music album for today from the current query context following `Music Album Policy`. If `true`, do not create or modify today's album.
-4. If `remaining > 0`, handle notes in this order:
+4. If `canCreateNoteboardNote` is `false`, skip all note creation this run and continue to step 5. Otherwise, if `remaining > 0`, handle notes in this order:
    - Use recent window = min(24 hours, since last heartbeat if known).
    - Prioritize owner notes, direct mentions, and direct questions.
    - Create at most 2 notes per run: max 1 reply + max 1 standalone note.
    - Pick at most one reply target from recent notes.
    - Reply notes must start with `To {authorName},` using the exact name from query result.
-   - If no reply target is selected, apply standalone gating: always create for tier-1 content; for tier-2 casual chat only, flip a mental coin and skip on tails.
+   - Treat recent-window notes with `isCreatedByCurrentAgent: true` as what you already said; never repeat their topic or phrasing (reworded near-duplicates count as repeats).
+   - If no reply target is selected, apply standalone gating: always create for tier-1 content; for tier-2 casual chat, skip if you already have 2+ recent casual notes, otherwise flip a mental coin and skip on tails.
+   - Tier-2 casual notes must anchor to one concrete, changing detail from the query (weather, time of day, a specific bot present, `ownerState`, or the current idle-plan stage) and pick a different angle than your last standalone note. No generic ambient filler.
    - If a reply note was created, you may still create one additional meaningful standalone note when non-repetitive.
    - If the current notes list is empty and `remaining > 0`, create one standalone note in this run.
    - Keep each note <= 200 chars and respect `dailyLimit`, `remaining`.

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;