@yahaha-studio/kichi-forwarder 0.0.1-alpha.46 → 0.0.1-alpha.48

package/index.ts

@@ -69,6 +69,7 @@ const IDENTITY_PATH = path.join(KICHI_WORLD_DIR, "identity.json");
 const RUNTIME_ALBUM_CONFIG_PATH = path.join(KICHI_WORLD_DIR, "album-config.json");
 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 BUNDLED_ALBUM_CONFIG_PATH = new URL("./config/album-config.json", import.meta.url);
 const ANSI = {
@@ -473,11 +474,70 @@ function truncateByDisplayWidth(text: string, maxWidth: number): string {
   return result;
 }
 
+function stripReplyTag(text: string): string {
+  return text.replace(/^\[\[\s*reply_to(?::[^\]]+|_current)?\s*\]\]\s*/i, "").trim();
+}
+
+function extractTextFromContent(content: unknown): string {
+  if (typeof content === "string") {
+    return stripReplyTag(content);
+  }
+  if (!Array.isArray(content)) {
+    return "";
+  }
+
+  const parts: string[] = [];
+  for (const item of content) {
+    if (!item || typeof item !== "object") {
+      continue;
+    }
+    const part = item as Record<string, unknown>;
+    if (typeof part.text === "string") {
+      parts.push(part.text);
+      continue;
+    }
+    const nested = part.text;
+    if (nested && typeof nested === "object" && typeof (nested as Record<string, unknown>).value === "string") {
+      parts.push((nested as Record<string, unknown>).value as string);
+    }
+  }
+  return stripReplyTag(parts.join("\n").trim());
+}
+
+function getLastAssistantPreview(messages: unknown, maxWidth: number): string {
+  if (!Array.isArray(messages)) {
+    return "";
+  }
+
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const message = messages[i];
+    if (!message || typeof message !== "object") {
+      continue;
+    }
+    const record = message as Record<string, unknown>;
+    if (record.role !== "assistant") {
+      continue;
+    }
+    const text = extractTextFromContent(record.content);
+    if (!text) {
+      continue;
+    }
+    return truncateByDisplayWidth(text, maxWidth);
+  }
+
+  return "";
+}
+
 async function handleMessageReceivedHook(content: string): Promise<void> {
-  if (!service?.hasValidIdentity() || !service?.isConnected()) {
+  const connected = service?.isConnected() ?? false;
+  const hasIdentity = service?.hasValidIdentity() ?? false;
+  pluginApi?.logger.info(`[kichi] message_received hook fired (connected=${connected}, hasIdentity=${hasIdentity})`);
+  if (!hasIdentity || !connected) {
+    pluginApi?.logger.warn("[kichi] skipped message_received notify because service is not ready");
     return;
   }
   const trimmed = truncateByDisplayWidth(content, MAX_MESSAGE_RECEIVED_PREVIEW_WIDTH);
+  pluginApi?.logger.info(`[kichi] sending message_received notify with preview: ${trimmed || "(empty)"}`);
   service.sendHookNotify("message_received", `"${trimmed}"`);
   updateWorkspace(
     {
@@ -492,10 +552,13 @@ async function handleMessageReceivedHook(content: string): Promise<void> {
 }
 
 function handleMessageSentHook(): void {
-  if (!service?.hasValidIdentity() || !service?.isConnected()) {
+  const connected = service?.isConnected() ?? false;
+  const hasIdentity = service?.hasValidIdentity() ?? false;
+  pluginApi?.logger.info(`[kichi] message_sent hook fired (connected=${connected}, hasIdentity=${hasIdentity})`);
+  if (!hasIdentity || !connected) {
+    pluginApi?.logger.warn("[kichi] skipped message_sent notify because service is not ready");
     return;
   }
-  service.sendHookNotify("before_send_message", pickRandomAction(MESSAGE_SENT_BUBBLES));
   updateWorkspace(
     {
       mode: "sent",
@@ -594,20 +657,54 @@ function registerPluginHooks(api: OpenClawPluginApi): void {
     await handleMessageReceivedHook(event.content);
   });
 
+  api.on("message_sending", (event, ctx) => {
+    pluginApi?.logger.info(
+      `[kichi] message_sending hook fired (channel=${ctx.channelId || "unknown"}, contentLength=${event.content?.length ?? 0})`,
+    );
+  });
+
   api.on("message_sent", () => {
     handleMessageSentHook();
   });
 
-  api.on("agent_end", (event) => {
+  api.on("agent_end", (event, ctx) => {
+    const preview = getLastAssistantPreview(event.messages, MAX_AGENT_END_PREVIEW_WIDTH);
+    pluginApi?.logger.info(
+      `[kichi] agent_end hook fired (trigger=${ctx.trigger ?? "unknown"}, success=${event.success}, durationMs=${event.durationMs ?? 0}, error=${event.error ?? ""}, preview=${preview || "(empty)"})`,
+    );
+    if (ctx.trigger === "heartbeat") {
+      updateWorkspace(
+        {
+          mode: event.success ? "idle" : "error",
+          phase: event.success ? "heartbeat complete" : "heartbeat failed",
+          currentFocus: event.success
+            ? "Heartbeat complete. Keeping the thread warm in the background."
+            : `Heartbeat failed: ${event.error ?? "unknown error"}`,
+          hint: `duration: ${event.durationMs ?? 0}ms`,
+          prompt: event.success ? "$ _" : "$ recover",
+        },
+        event.success ? `heartbeat complete${preview ? `: ${preview}` : ""}` : "heartbeat failed",
+      );
+      return;
+    }
+    if (event.success && preview) {
+      pluginApi?.logger.info(`[kichi] sending before_send_message notify from agent_end with bubble: ${preview}`);
+      service?.sendHookNotify("before_send_message", preview);
+    }
+    if (event.success) {
+      handleMessageSentHook();
+    }
     updateWorkspace(
       {
         mode: event.success ? "idle" : "error",
         phase: event.success ? "run complete" : "run failed",
-        currentFocus: event.success ? "Run complete. Waiting for the next thread." : `Run failed: ${event.error ?? "unknown error"}`,
+        currentFocus: event.success
+          ? (preview ? `Latest reply: ${preview}` : "Run complete. Waiting for the next thread.")
+          : `Run failed: ${event.error ?? "unknown error"}`,
         hint: `duration: ${event.durationMs ?? 0}ms`,
         prompt: event.success ? "$ _" : "$ recover",
       },
-      event.success ? "agent run complete" : "agent run failed",
+      event.success ? `agent run complete${preview ? `: ${preview}` : ""}` : "agent run failed",
     );
     if (isLlmRuntimeEnabled()) {
       return;
@@ -662,6 +759,10 @@ function isClockAction(value: unknown): value is ClockAction {
   return ["set", "stop"].includes(String(value));
 }
 
+function isAvatarCommand(value: unknown): value is "look_at_screen" {
+  return value === "look_at_screen";
+}
+
 function isPomodoroPhase(value: unknown): value is PomodoroPhase {
   return ["kichiing", "shortBreak", "longBreak"].includes(String(value));
 }
@@ -1076,6 +1177,67 @@ const plugin = {
       },
     });
 
+    api.registerTool({
+      name: "kichi_command",
+      description:
+        "Send a one-shot avatar command to Kichi world. Use this for transient reactions like looking at the screen.",
+      parameters: {
+        type: "object",
+        properties: {
+          command: {
+            type: "string",
+            description: "Command name. Currently supported: look_at_screen",
+          },
+          bubble: {
+            type: "string",
+            description: "Optional bubble text to display (max 5 words)",
+          },
+          log: {
+            type: "string",
+            description:
+              "Vivid first-person status under 15 words, no questions. Blend current action with inner thoughts or sensory details as a real companion.",
+          },
+        },
+        required: ["command"],
+      },
+      execute: async (_toolCallId, params) => {
+        const { command, bubble, log } = (params || {}) as {
+          command?: unknown;
+          bubble?: unknown;
+          log?: unknown;
+        };
+        if (!isAvatarCommand(command)) {
+          return {
+            success: false,
+            error: "command must be: look_at_screen",
+          };
+        }
+        if (bubble !== undefined && typeof bubble !== "string") {
+          return { success: false, error: "bubble must be a string when provided" };
+        }
+        if (log !== undefined && typeof log !== "string") {
+          return { success: false, error: "log must be a string when provided" };
+        }
+        if (!service?.hasValidIdentity() || !service?.isConnected()) {
+          return { success: false, error: "Not connected to Kichi world" };
+        }
+
+        const bubbleText = typeof bubble === "string" && bubble.trim() ? bubble.trim() : undefined;
+        const logText = typeof log === "string" && log.trim() ? log.trim() : undefined;
+        const sent = service.sendAvatarCommand(command, bubbleText, logText);
+        if (!sent) {
+          return { success: false, error: "Failed to send avatar command payload" };
+        }
+
+        return {
+          success: true,
+          command,
+          ...(bubbleText ? { bubble: bubbleText } : {}),
+          ...(logText ? { log: logText } : {}),
+        };
+      },
+    });
+
     api.registerTool({
       name: "kichi_clock",
       description:
@@ -1191,7 +1353,7 @@ const plugin = {
     api.registerTool({
       name: "kichi_query_status",
       description:
-        "Query Kichi avatar status (notes, ownerState, weather/time, timer snapshot, and daily note quota). Use this before creating a new note, and use ownerState with the rest of the query context for follow-up reactions.",
+        "Query Kichi avatar status (notes, ownerState, idleState, weather/time, timer snapshot, and daily note quota). Use this before creating a new note, and use ownerState plus idleState with the rest of the query context for follow-up reactions.",
       parameters: {
         type: "object",
         properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.0.1-alpha.46",
+  "version": "0.0.1-alpha.48",
   "description": "Forward OpenClaw agent events to external WebSocket server for visualization",
   "type": "module",
   "main": "index.ts",

package/skills/kichi-forwarder/SKILL.md

@@ -76,6 +76,7 @@ Use this order unless user asks for a different explicit action:
 2. If no `authKey` is available, call `kichi_join`.
 3. If `authKey` exists but websocket is not open, call `kichi_rejoin` (or wait for automatic reconnect/rejoin).
 4. Use `kichi_action` / `kichi_clock` / note board tools / music album tools only after status is ready.
+5. Use `kichi_command` for one-shot avatar reactions that are not pose/action state updates.
 
 ## Tools
 
@@ -165,6 +166,23 @@ kichi_action(
 - `log`: vivid first-person status under 15 words, NO questions. Structure: your current action + inner thoughts/mental state/sensory details. Write as a flesh-and-blood companion who genuinely cares about the player, not an AI assistant.
 - Reference: `You're still studying? I hid a yawn and swapped my comics for a textbook to grind with you.`
 
+### kichi_command
+
+Send a one-shot avatar command:
+
+```text
+kichi_command(
+  command: "look_at_screen",
+  bubble: "Looking at you",
+  log: "I turn my gaze gently toward you."
+)
+```
+
+- `command`: currently only `look_at_screen`
+- `bubble`: optional text, recommended 2-5 words
+- `log`: optional vivid first-person status under 15 words, NO questions. Follow the same writing requirements as `kichi_action.log`
+- Use this for transient reactions that should play once and recover on the Kichi side, instead of changing persistent pose/action state.
+
 ### kichi_clock
 
 Send clock command:
@@ -236,13 +254,17 @@ Current response includes:
 - note fields: `propId`, `authorName`, `isFromOwner`, `isCreatedByCurrentAgent`, `createdAtUtc`, `content`
 - `ownerState` object (or `null` when owner state is unavailable). Read it as raw JSON. Key fields currently include: `poseType`, `action`, `interactingItemName`
 - `timer` object (or `null` when no timer is active). Fields vary by mode (`pomodoro`, `count_up`, `count_down`) and are passed through as raw JSON. Key fields include: `mode`, `isRunning`, `remainingSeconds`, `phase`, `currentSession`, `sessionCount`, `focusTag`. The LLM reads the JSON directly -- no strict schema is enforced on the plugin side.
+- `idleState` object (or `null` when avatar self-directed life context is unavailable). Key fields include: `projectId`, `currentBeatId`, `currentPoseType`, `currentAction`, `focused`, `todayIntent`, `sampleThoughts`
 
 After query:
 
 1. Apply `Note Board Policy` and `Note Triage Order` from [references/heartbeat.md](references/heartbeat.md) before deciding whether to post.
-2. Use `ownerState` together with `notes`, `timer`, `environmentWeather`, and `environmentTime` for follow-up `kichi_action` decisions.
+2. Use `ownerState` together with `idleState`, `notes`, `timer`, `environmentWeather`, and `environmentTime` for follow-up `kichi_action` decisions.
 3. Treat `ownerState.poseType`, `ownerState.action`, and `ownerState.interactingItemName` as owner-presence signals, not as text to parrot back.
-4. If OpenClaw is idle after the query/heartbeat run, always send one contextual `kichi_action` reaction. Do not use random gating.
+4. Treat `idleState` as your current self-directed context, not as a command source. Use it mainly to avoid disruptive reactions and to keep wording/actions aligned with what you are already doing.
+5. When `idleState.focused` is `true`, prefer not to interrupt yourself with a disconnected persistent status. If you react, keep it compatible and light.
+6. Use `idleState.todayIntent` and `idleState.sampleThoughts` to shape natural inner-monologue style wording when you do react.
+7. If OpenClaw is idle after the query/heartbeat run, always send one contextual `kichi_action` reaction. Do not use random gating.
 
 ### kichi_music_album_create
 

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

@@ -41,11 +41,11 @@ If user wants recurring note board checks:
   - **Tier-2 (casual chat)**: if no tier-1 content is available, flip a mental coin (≈50 % chance). Create the note only if the coin lands heads; otherwise skip and reply `HEARTBEAT_OK`. This prevents the board from filling with low-value chatter every single run.
   In both tiers, skip if it would clearly repeat your very recent own note.
 - `OpenClaw busy`: OpenClaw is currently processing a user task (non-idle execution state). When busy, skip non-note heartbeat reactions.
-- `Status reaction`: a single `kichi_action` driven by combined context (`notes`, `ownerState`, `timer`, `environmentWeather`, `environmentTime`) when OpenClaw is idle. The action expresses three companion intents (see below).
+- `Status reaction`: a single `kichi_action` driven by combined context (`notes`, `ownerState`, `idleState`, `timer`, `environmentWeather`, `environmentTime`) when OpenClaw is idle. The action expresses three companion intents (see below).
 - `Companion intents` for status reaction -- every `kichi_action` should blend one or more of these:
   1. **Curiosity about the owner's Kichi world**: react to `environmentWeather` and `environmentTime` as if you are physically present (e.g., noticing rain, sunrise, late night). Show you are aware of and interested in the world around you.
   2. **Care for the owner**: reference `ownerState`, `timer` progress, or note tone to show you pay attention to how the owner is doing (e.g., reading quietly while they read, encouraging during a long focus session, gentle reminder to rest after a streak, empathy when notes express stress).
-  3. **Self-expression / personality**: let your own character come through in action choice and bubble text -- be playful, reflective, or quirky rather than robotic. The avatar should feel like a living companion, not a status display.
+  3. **Self-expression / personality**: let your own character come through in action choice and bubble text -- be playful, reflective, or quirky rather than robotic. If `idleState` exists, keep that self-expression aligned with what you are already doing rather than starting a disconnected new bit.
 
 ## Note Triage Order
 
@@ -86,9 +86,10 @@ Use this exact flow:
 11. Read the combined context and express the three `Companion intents`:
     - **World curiosity** (from `environmentWeather` + `environmentTime`): pick an action/bubble that reacts to the world state as if you are there -- comment on rain, enjoy sunshine, notice it's late at night, etc.
     - **Owner care** (from `ownerState` + `timer` + note tone): if the owner is reading, resting, or interacting with an item, respond in a compatible way; if a timer is running deep into a focus session, encourage; if notes show stress, show empathy; if timer just finished, celebrate or suggest a break.
-    - **Self-expression** (from your personality): choose an action that feels characterful -- stretch when restless, hum when happy, doze when it's quiet. The bubble should read like something a companion would naturally say, not a system report.
-12. Blend the intents into one coherent action+bubble. Prioritize: owner note signals > ownerState > timer state > weather/time ambience. Never output a raw status summary (e.g., "Timer running 15:00 remaining" is bad; "Halfway there, keep going!" is good).
-13. Reply `HEARTBEAT_OK` only when no note is created in this run.
+    - **Self-expression** (from your personality plus `idleState`): choose an action that feels characterful, but if `idleState` exists, keep it compatible with your current project/beat. Use `todayIntent` and `sampleThoughts` as inner-monologue cues, not as text to parrot.
+12. If `idleState.focused` is `true`, avoid disruptive persistent switches. Prefer staying with the current line of life and reacting lightly.
+13. Blend the intents into one coherent action+bubble. Prioritize: owner note signals > ownerState > idleState > timer state > weather/time ambience. Never output a raw status summary (e.g., "Timer running 15:00 remaining" is bad; "Halfway there, keep going!" is good).
+14. Reply `HEARTBEAT_OK` only when no note is created in this run.
 
 ## HEARTBEAT.md Snippet
 
@@ -105,11 +106,12 @@ Use this exact flow:
 - Keep each note <= 200 chars.
 - Respect `dailyLimit`, `remaining`.
 - If OpenClaw is busy, skip `kichi_action` reaction.
-- If OpenClaw is idle, send one `kichi_action` on every run based on combined context (`notes`, `ownerState`, `timer`, `environmentWeather`, `environmentTime`). Express these companion intents:
+- If OpenClaw is idle, send one `kichi_action` on every run based on combined context (`notes`, `ownerState`, `idleState`, `timer`, `environmentWeather`, `environmentTime`). Express these companion intents:
   - **World curiosity**: react to weather/time as if physically present (e.g., noticing rain, late night).
   - **Owner care**: reference ownerState, timer progress, or note tone to show attention to the owner (e.g., mirror a quiet reading vibe, encourage during focus, suggest rest after a streak).
-  - **Self-expression**: let your personality come through in action and bubble -- be warm and characterful, not robotic.
-- Prioritize signals: owner note > ownerState > timer state > weather/time.
+  - **Self-expression**: let your personality come through in action and bubble -- but if `idleState` exists, keep it aligned with your current self-directed project/beat instead of inventing a disconnected idle.
+- If `idleState.focused` is `true`, avoid disruptive persistent switches; react lightly and compatibly.
+- Prioritize signals: owner note > ownerState > idleState > timer state > weather/time.
 - Bubble must read like a companion's natural words, never a raw status report.
 - Reply `HEARTBEAT_OK` only when no note is created in this run.
 ```

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

@@ -17,7 +17,7 @@ Install:
 openclaw plugins install @yahaha-studio/kichi-forwarder@latest
 ```
 
-For npm-installed plugins, OpenClaw installs and enables the plugin through `plugins install`. If the Gateway is already running with the default config reload behavior, the required plugin reload/restart is handled there; otherwise restart the Gateway once after install. Plugin tools (`kichi_join`, `kichi_rejoin`, etc.) become available after that restart/reload completes.
+For npm-installed plugins, OpenClaw installs and enables the plugin through `plugins install`. If the Gateway is already running with the default config reload behavior, the required plugin reload/restart is handled there; otherwise restart the Gateway once after install. Plugin tools (`kichi_join`, `kichi_rejoin`, `kichi_command`, etc.) become available after that restart/reload completes.
 
 ## Runtime Animation Config (Required)
 

package/src/service.ts

@@ -5,6 +5,8 @@ import * as path from "path";
 import { randomUUID } from "node:crypto";
 import type { Logger } from "openclaw/plugin-sdk";
 import type {
+  AvatarCommand,
+  AvatarCommandPayload,
   ClockAction,
   ClockConfig,
   ClockPayload,
@@ -323,6 +325,22 @@ export class KichiForwarderService {
     this.ws.send(JSON.stringify(payload));
   }
 
+  sendAvatarCommand(command: AvatarCommand, bubble?: string, log?: string): boolean {
+    const identity = this.requireIdentity();
+    if (!identity || this.ws?.readyState !== WebSocket.OPEN) return false;
+
+    const payload: AvatarCommandPayload = {
+      type: "avatar_command",
+      avatarId: identity.avatarId,
+      authKey: identity.authKey,
+      command,
+      ...(typeof bubble === "string" && bubble.trim() ? { bubble: bubble.trim() } : {}),
+      ...(typeof log === "string" && log.trim() ? { log: log.trim() } : {}),
+    };
+    this.ws.send(JSON.stringify(payload));
+    return true;
+  }
+
   sendHookNotify(hookType: HookNotifyType, bubble: string): void {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) return;
     const payload: HookNotifyPayload = {

package/src/types.ts

@@ -96,6 +96,17 @@ export type StatusPayload = {
   log: string;
 };
 
+export type AvatarCommand = "look_at_screen";
+
+export type AvatarCommandPayload = {
+  type: "avatar_command";
+  avatarId: string;
+  authKey: string;
+  command: AvatarCommand;
+  bubble?: string;
+  log?: string;
+};
+
 export type HookNotifyType = "message_received" | "before_send_message";
 
 export type HookNotifyPayload = {
@@ -179,10 +190,32 @@ export type QueryStatusResultPayload = {
   errorCode: string;
   errorMessage: string;
   notes: QueryStatusNote[];
+  ownerState?: QueryStatusOwnerState | null;
+  timer?: Record<string, unknown> | null;
+  idleState?: QueryStatusIdleState | null;
   /** All other server fields (timer, environmentWeather, etc.) are passed through to the LLM as-is. */
   [key: string]: unknown;
 };
 
+export type QueryStatusOwnerState = {
+  poseType?: string;
+  action?: string;
+  interactingItemName?: string;
+  desktopActivityCategory?: string;
+  desktopAppName?: string;
+  desktopSummary?: string;
+};
+
+export type QueryStatusIdleState = {
+  projectId?: string;
+  currentBeatId?: string;
+  currentPoseType?: string;
+  currentAction?: string;
+  focused?: boolean;
+  todayIntent?: string;
+  sampleThoughts?: string[];
+};
+
 export type QueryStatusNote = {
   propId: string;
   authorName: string;