@yahaha-studio/kichi-forwarder 0.0.1-alpha.45 → 0.0.1-alpha.47

package/index.ts

@@ -106,6 +106,10 @@ type WorkspaceScreenState = {
   currentFocus: string;
   hint: string;
   prompt: string;
+  title: string;
+  shellName: string;
+  cwdLabel: string;
+  modelLabel: string;
 };
 
 function createWorkspaceScreenState(): WorkspaceScreenState {
@@ -118,7 +122,43 @@ function createWorkspaceScreenState(): WorkspaceScreenState {
     recentActivity: [],
     currentFocus: "Waiting for the next thread to pick up.",
     hint: "Low-noise live workspace view.",
-    prompt: "kiro@room:~$ _",
+    prompt: "$ _",
+    title: "Workspace",
+    shellName: "agent",
+    cwdLabel: process.cwd(),
+    modelLabel: "model: unknown",
+  };
+}
+
+function normalizeShellToken(value: string): string {
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized || "agent";
+}
+
+function parseIdentityNameFromWorkspace(workspaceRoot: string): string | null {
+  try {
+    const identityPath = path.join(workspaceRoot, "IDENTITY.md");
+    if (!fs.existsSync(identityPath)) return null;
+    const raw = fs.readFileSync(identityPath, "utf-8");
+    const match = raw.match(/^-\s*\*\*Name:\*\*\s*(.+)$/m);
+    const value = match?.[1]?.trim();
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+function deriveWorkspaceIdentity(workspaceRoot: string): Pick<WorkspaceScreenState, "title" | "shellName" | "cwdLabel"> {
+  const identityName = parseIdentityNameFromWorkspace(workspaceRoot);
+  const titleBase = identityName || path.basename(workspaceRoot) || "workspace";
+  return {
+    title: `${titleBase} Workspace`,
+    shellName: normalizeShellToken(identityName || titleBase),
+    cwdLabel: workspaceRoot,
   };
 }
 
@@ -161,7 +201,7 @@ function pushActivity(line: string): void {
 
 function renderWorkspaceScreen(): string {
   const innerWidth = WORKSPACE_SCREEN_WIDTH - 2;
-  const topTitle = `${color(" Kiro Workspace ", "bold")}${color("live session", "gray")}`;
+  const topTitle = `${color(` ${workspaceState.title} `, "bold")}${color("live session", "gray")}`;
   const topLine = `╭─── ${topTitle}${"─".repeat(Math.max(0, innerWidth - 4 - visibleLength(topTitle)))}╮`;
   const bottomLine = `╰${"─".repeat(innerWidth)}╯`;
 
@@ -191,8 +231,8 @@ function renderWorkspaceScreen(): string {
   pushRow(`${color("  Hint", "cyan")}`);
   pushRow(`  ${truncatePlain(workspaceState.hint, innerWidth - 2)}`);
   pushRow("");
-  pushRow(`  ${color("openai/gpt-5.4", "magenta")}`);
-  pushRow(`  ${color("/Users/xiaoxinshi/.openclaw/workspace", "blue")}`);
+  pushRow(`  ${color(workspaceState.modelLabel, "magenta")}`);
+  pushRow(`  ${color(workspaceState.cwdLabel, "blue")}`);
   pushRow(`  ${color(`updated: ${workspaceState.updatedAtLabel}`, "gray")}`);
   pushRow("");
 
@@ -202,7 +242,7 @@ function renderWorkspaceScreen(): string {
     bottomLine,
     "",
     color("─".repeat(WORKSPACE_SCREEN_WIDTH), "gray"),
-    `${color("kiro@room", "green")}:${color("~", "blue")}$ ${workspaceState.prompt.replace(/^kiro@room:~\$\s*/, "")}`,
+    `${color(workspaceState.shellName, "green")}:${color("~", "blue")} ${workspaceState.prompt}`,
   ].join("\n");
 }
 
@@ -434,10 +474,15 @@ function truncateByDisplayWidth(text: string, maxWidth: number): string {
 }
 
 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(
     {
@@ -445,24 +490,30 @@ async function handleMessageReceivedHook(content: string): Promise<void> {
       phase: "processing inbound message",
       currentFocus: trimmed ? `User message: ${trimmed}` : "Reading the latest message.",
       hint: "Inbound message updated the live workspace.",
-      prompt: "kiro@room:~$ reading-message",
+      prompt: "$ reading-message",
     },
     `received message: ${trimmed || "(empty)"}`,
   );
 }
 
 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));
+  const bubble = pickRandomAction(MESSAGE_SENT_BUBBLES);
+  pluginApi?.logger.info(`[kichi] sending before_send_message notify with bubble: ${bubble}`);
+  service.sendHookNotify("before_send_message", bubble);
   updateWorkspace(
     {
       mode: "sent",
       phase: "message delivered",
       currentFocus: "Latest reply has been sent to the active chat.",
       hint: "Workspace settles after delivery.",
-      prompt: "kiro@room:~$ idle",
+      prompt: "$ idle",
     },
     "sent assistant reply",
   );
@@ -476,7 +527,7 @@ function registerPluginHooks(api: OpenClawPluginApi): void {
         phase: "building prompt",
         currentFocus: "Preparing the next response from current session context.",
         hint: "Prompt assembly is in progress.",
-        prompt: "kiro@room:~$ build-prompt",
+        prompt: "$ build-prompt",
       },
       "building prompt context",
     );
@@ -499,7 +550,8 @@ function registerPluginHooks(api: OpenClawPluginApi): void {
         phase: `llm input · ${event.model}`,
         currentFocus: "Feeding the model the current thread and constraints.",
         hint: `provider: ${event.provider} · images: ${event.imagesCount}`,
-        prompt: "kiro@room:~$ llm-input",
+        prompt: "$ llm-input",
+        modelLabel: `${event.provider}/${event.model}`,
       },
       `entered llm input: ${event.model}`,
     );
@@ -512,7 +564,8 @@ function registerPluginHooks(api: OpenClawPluginApi): void {
         phase: `llm output · ${event.model}`,
         currentFocus: "Shaping model output into the visible reply.",
         hint: `assistant chunks: ${event.assistantTexts.length}`,
-        prompt: "kiro@room:~$ draft-reply",
+        prompt: "$ draft-reply",
+        modelLabel: `${event.provider}/${event.model}`,
       },
       `received llm output: ${event.model}`,
     );
@@ -525,7 +578,7 @@ function registerPluginHooks(api: OpenClawPluginApi): void {
         phase: `running ${event.toolName}`,
         currentFocus: `Tool call in flight: ${event.toolName}`,
         hint: `tool context: ${ctx.toolName}`,
-        prompt: `kiro@room:~$ tool ${event.toolName}`,
+        prompt: `$ tool ${event.toolName}`,
       },
       `tool start: ${event.toolName}`,
     );
@@ -541,7 +594,7 @@ function registerPluginHooks(api: OpenClawPluginApi): void {
         phase: `tool finished ${event.toolName}`,
         currentFocus: `Tool result returned from ${event.toolName}.`,
         hint: event.error ? `tool error: ${event.error}` : `tool completed in ${event.durationMs ?? 0}ms`,
-        prompt: `kiro@room:~$ continue ${event.toolName}`,
+        prompt: `$ continue ${event.toolName}`,
       },
       event.error ? `tool error: ${event.toolName}` : `tool done: ${event.toolName}`,
     );
@@ -552,18 +605,30 @@ 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) => {
+    pluginApi?.logger.info(
+      `[kichi] agent_end hook fired (success=${event.success}, durationMs=${event.durationMs ?? 0}, error=${event.error ?? ""})`,
+    );
+    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"}`,
         hint: `duration: ${event.durationMs ?? 0}ms`,
-        prompt: event.success ? "kiro@room:~$ _" : "kiro@room:~$ recover",
+        prompt: event.success ? "$ _" : "$ recover",
       },
       event.success ? "agent run complete" : "agent run failed",
     );
@@ -620,6 +685,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));
 }
@@ -828,7 +897,11 @@ const plugin = {
           ctx.config.plugins?.entries?.["kichi-forwarder"]?.config,
         ) as KichiForwarderConfig;
         service = new KichiForwarderService(cfg, api.logger);
-        workspaceState = createWorkspaceScreenState();
+        const workspaceRoot = ctx.repoPath ?? "/Users/xiaoxinshi/.openclaw/workspace";
+        workspaceState = {
+          ...createWorkspaceScreenState(),
+          ...deriveWorkspaceIdentity(workspaceRoot),
+        };
         workspaceState.channel = ctx.channelId ?? "unknown";
         scheduleWorkspacePush();
         return service.start();
@@ -1030,6 +1103,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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.0.1-alpha.45",
+  "version": "0.0.1-alpha.47",
   "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:

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 = {