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

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}`);
@@ -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}`);
@@ -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.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.21",
+  "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

@@ -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/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;