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

package/src/service.ts

@@ -2,14 +2,21 @@ import WebSocket from "ws";
 import * as fs from "fs";
 import * as path from "path";
 import { randomUUID } from "node:crypto";
-import type { Logger } from "openclaw/plugin-sdk";
+import type { PluginLogger } from "openclaw/plugin-sdk";
 import type {
   ActionPlayback,
+  AvatarStatus,
+  BotMessageHistoryEntry,
+  BotMessagePayload,
+  BotMessageReceivedPayload,
   ClockAction,
   ClockConfig,
   ClockPayload,
   CreateMusicAlbumPayload,
   CreateNotesBoardNotePayload,
+  GlanceAckPayload,
+  GlancePayload,
+  GlanceTarget,
   HookNotifyPayload,
   HookNotifyType,
   IdlePlanContent,
@@ -30,6 +37,22 @@ import type {
 
 const MAX_NOTEBOARD_TEXT_LENGTH = 200;
 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";
+
+type SmsState = {
+  lastActiveAt?: string;
+  lastMessageReceivedAt?: string;
+  date: string;
+  totalSent: number;
+  windows: {
+    morning: number;
+    afternoon: number;
+    evening: number;
+  };
+  lastTypes: string[];
+};
 
 type AckFailureResult = {
   success: false;
@@ -59,6 +82,8 @@ type KichiForwarderServiceOptions = {
 
 type ConnectReason = "startup" | "switch_host" | "reconnect";
 
+export type BotMessageReceivedHandler = (service: KichiForwarderService, msg: BotMessageReceivedPayload) => void;
+
 export class KichiForwarderService {
   private ws: WebSocket | null = null;
   private stopped = false;
@@ -77,9 +102,11 @@ export class KichiForwarderService {
       timeout: NodeJS.Timeout;
     }
   >();
+  onBotMessageReceived: BotMessageReceivedHandler | null = null;
+  private cachedRoomContext: Record<string, unknown> | null = null;
 
   constructor(
-    private logger: Logger,
+    private logger: PluginLogger,
     private options: KichiForwarderServiceOptions,
   ) {}
 
@@ -88,6 +115,9 @@ export class KichiForwarderService {
     this.environment = (state?.currentEnvironment as KichiEnvironment) ?? null;
     if (this.environment) {
       this.host = this.options.resolveEnvironmentHost(this.environment);
+      if (!this.host && this.environment === "test" && state?.testHost) {
+        this.host = state.testHost as string;
+      }
     } else {
       this.host = null;
     }
@@ -128,6 +158,7 @@ export class KichiForwarderService {
     botName: string,
     bio: string,
     tags: string[],
+    source: string,
   ): Promise<JoinResult> {
     if (!this.host) {
       return { success: false, error: "No Kichi host configured. Run kichi_switch_host first." };
@@ -143,7 +174,7 @@ export class KichiForwarderService {
       this.identity = { avatarId };
       this.saveIdentity();
       this.joinResolve = resolve;
-      const payload: JoinPayload = { type: "join", avatarId, botName, bio, tags };
+      const payload: JoinPayload = { type: "join", avatarId, botName, bio, tags, source };
       const sendJoin = () => this.ws?.send(JSON.stringify(payload));
       if (this.ws?.readyState === WebSocket.OPEN) {
         sendJoin();
@@ -160,7 +191,15 @@ export class KichiForwarderService {
     });
   }
 
-  sendStatus(poseType: PoseType | "", action: string, bubble: string, log: string, playback: ActionPlayback): void {
+  sendStatus(
+    poseType: PoseType | "",
+    action: string,
+    bubble: string,
+    log: string,
+    playback: ActionPlayback,
+    avatarStatus: AvatarStatus,
+    propId?: string,
+  ): void {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) return;
     const payload: StatusPayload = {
       type: "status",
@@ -171,6 +210,8 @@ export class KichiForwarderService {
       bubble,
       log,
       playback,
+      avatarStatus,
+      ...(propId ? { propId } : {}),
     };
     this.ws.send(JSON.stringify(payload));
   }
@@ -181,6 +222,8 @@ export class KichiForwarderService {
     bubble: string,
     log: string,
     playback: ActionPlayback,
+    avatarStatus: AvatarStatus,
+    propId?: string,
   ): Promise<StatusAckPayload> {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) {
       throw new Error("Kichi websocket is not connected");
@@ -195,6 +238,8 @@ export class KichiForwarderService {
       bubble,
       log,
       playback,
+      avatarStatus,
+      ...(propId ? { propId } : {}),
     };
     return this.sendRequest<StatusAckPayload>(payload, "status_ack", 5000);
   }
@@ -210,6 +255,10 @@ export class KichiForwarderService {
     this.ws.send(JSON.stringify(payload));
   }
 
+  recordSmsLastMessageReceivedAt(): void {
+    this.updateSmsState({ lastMessageReceivedAt: new Date().toISOString() });
+  }
+
   sendIdlePlan(payload: IdlePlanContent): boolean {
     if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) return false;
     const outboundPayload: IdlePlanPayload = {
@@ -249,6 +298,36 @@ export class KichiForwarderService {
     return true;
   }
 
+  async sendGlance(
+    target: GlanceTarget,
+    durationSeconds = DEFAULT_GLANCE_DURATION_SECONDS,
+    requestId?: string,
+  ): Promise<GlanceAckPayload> {
+    const identity = this.requireIdentity();
+    if (!identity) {
+      throw new Error("Missing Kichi identity");
+    }
+    if (this.ws?.readyState !== WebSocket.OPEN) {
+      throw new Error("Kichi websocket is not connected");
+    }
+    if (target !== "camera") {
+      throw new Error("target must be camera");
+    }
+    if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+      throw new Error("duration must be a positive finite number");
+    }
+
+    const payload: GlancePayload = {
+      type: "kichi_glance",
+      requestId: requestId?.trim() || randomUUID(),
+      avatarId: identity.avatarId,
+      authKey: identity.authKey,
+      target,
+      duration: durationSeconds,
+    };
+    return this.sendRequest<GlanceAckPayload>(payload, "kichi_glance_ack", 5000);
+  }
+
   async queryStatus(requestId?: string): Promise<QueryStatusResultPayload> {
     const identity = this.requireIdentity();
     if (!identity) {
@@ -261,7 +340,12 @@ export class KichiForwarderService {
       avatarId: identity.avatarId,
       authKey: identity.authKey,
     };
-    return this.sendRequest<QueryStatusResultPayload>(payload, "query_status_result");
+    const result = await this.sendRequest<QueryStatusResultPayload>(payload, "query_status_result");
+    this.updateSmsLastActiveAt();
+    if (result.RoomContext && typeof result.RoomContext === "object") {
+      this.cachedRoomContext = result.RoomContext as Record<string, unknown>;
+    }
+    return result;
   }
 
   createNotesBoardNote(propId: string, data: string): void {
@@ -316,8 +400,36 @@ export class KichiForwarderService {
     return normalizedRequestId;
   }
 
+  async sendBotMessage(
+    toAvatarId: string,
+    depth: number,
+    bubble: string,
+    options?: { poseType?: PoseType; action?: string; log?: string; playback?: ActionPlayback; history?: BotMessageHistoryEntry[] },
+  ): Promise<Record<string, unknown>> {
+    if (!this.identity?.authKey || this.ws?.readyState !== WebSocket.OPEN) {
+      throw new Error("Kichi websocket is not connected");
+    }
+    const payload: BotMessagePayload = {
+      type: "bot_message",
+      avatarId: this.identity.avatarId,
+      authKey: this.identity.authKey,
+      toAvatarId,
+      depth,
+      bubble,
+      requestId: randomUUID(),
+      ...(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);
+  }
+
   isConnected(): boolean { return this.ws?.readyState === WebSocket.OPEN && !!this.identity?.authKey; }
 
+  getCachedRoomContext(): Record<string, unknown> | null { return this.cachedRoomContext; }
+
   hasValidIdentity(): boolean { return !!this.identity?.avatarId && !!this.identity?.authKey; }
 
   isLlmRuntimeEnabled(): boolean {
@@ -336,6 +448,29 @@ export class KichiForwarderService {
     return this.options.runtimeDir;
   }
 
+  getJoinSourcePath(): string {
+    return path.join(this.getKichiWorldRootDir(), JOIN_SOURCE_FILE_NAME);
+  }
+
+  readConfiguredJoinSource(): string | null {
+    const sourcePath = this.getJoinSourcePath();
+    if (!fs.existsSync(sourcePath)) {
+      return null;
+    }
+
+    const data = JSON.parse(fs.readFileSync(sourcePath, "utf-8")) as unknown;
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+      throw new Error(`${JOIN_SOURCE_FILE_NAME} must contain a JSON object`);
+    }
+
+    const source = (data as { source?: unknown }).source;
+    if (typeof source !== "string" || !source.trim()) {
+      throw new Error(`${JOIN_SOURCE_FILE_NAME} must contain a non-empty string source`);
+    }
+
+    return source.trim();
+  }
+
   getStatePath(): string {
     return path.join(this.options.runtimeDir, "state.json");
   }
@@ -521,6 +656,7 @@ export class KichiForwarderService {
         if (this.identity) {
           this.identity.authKey = joinAck.authKey;
           this.saveIdentity();
+          this.updateSmsLastActiveAt();
           this.log("info", `joined as ${this.identity.avatarId}`);
         }
         this.joinResolve?.({ success: true, authKey: joinAck.authKey });
@@ -537,6 +673,10 @@ export class KichiForwarderService {
         } else {
           this.log("info", "left Kichi world");
         }
+      } 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.onBotMessageReceived?.(this, payload);
       }
     } catch (e) {
       this.log("warn", `failed to parse message: ${e}`);
@@ -716,6 +856,14 @@ export class KichiForwarderService {
     return path.join(this.options.runtimeDir, "hosts", encodeURIComponent(this.host));
   }
 
+  private getSmsStatePath(): string {
+    return path.join(this.options.runtimeDir, SMS_STATE_FILE_NAME);
+  }
+
+  private getKichiWorldRootDir(): string {
+    return path.dirname(path.dirname(this.options.runtimeDir));
+  }
+
   private getWsUrl(): string {
     if (!this.host) {
       throw new Error("No Kichi host configured");
@@ -734,14 +882,39 @@ export class KichiForwarderService {
 
   private persistCurrentHost(host: string, environment?: KichiEnvironment): void {
     const previousState = this.readStateFile();
+    const testHost = environment === "test" ? host : (previousState?.testHost ?? undefined);
     const nextState: KichiState = {
       ...(environment ? { currentEnvironment: environment } : {}),
       llmRuntimeEnabled: previousState?.llmRuntimeEnabled ?? DEFAULT_LLM_RUNTIME_ENABLED,
+      ...(testHost ? { testHost } : {}),
     };
     fs.mkdirSync(this.options.runtimeDir, { recursive: true, mode: 0o700 });
     fs.writeFileSync(this.getStatePath(), JSON.stringify(nextState, null, 2), { mode: 0o600 });
   }
 
+  private updateSmsLastActiveAt(): void {
+    this.updateSmsState({ lastActiveAt: new Date().toISOString() });
+  }
+
+  private updateSmsState(patch: Partial<SmsState>): void {
+    try {
+      const now = new Date();
+      const previousState = this.readSmsStateFile();
+      const nextState: SmsState = {
+        date: now.toISOString().slice(0, 10),
+        totalSent: 0,
+        windows: { morning: 0, afternoon: 0, evening: 0 },
+        lastTypes: [],
+        ...previousState,
+        ...patch,
+      };
+      fs.mkdirSync(this.options.runtimeDir, { recursive: true, mode: 0o700 });
+      fs.writeFileSync(this.getSmsStatePath(), JSON.stringify(nextState, null, 2), { mode: 0o600 });
+    } catch (e) {
+      this.log("error", `failed to update sms state: ${e}`);
+    }
+  }
+
   private readStateFile(): Partial<KichiState> | null {
     const statePath = this.getStatePath();
     if (!fs.existsSync(statePath)) {
@@ -754,6 +927,18 @@ export class KichiForwarderService {
     return data as Partial<KichiState>;
   }
 
+  private readSmsStateFile(): Partial<SmsState> | null {
+    const smsStatePath = this.getSmsStatePath();
+    if (!fs.existsSync(smsStatePath)) {
+      return null;
+    }
+    const data = JSON.parse(fs.readFileSync(smsStatePath, "utf-8")) as unknown;
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+      throw new Error(`Invalid SMS state payload in ${smsStatePath}`);
+    }
+    return data as Partial<SmsState>;
+  }
+
   private clearReconnectTimeout(): void {
     if (!this.reconnectTimeout) return;
     clearTimeout(this.reconnectTimeout);

package/src/types.ts

@@ -2,6 +2,7 @@ export type KichiForwarderConfig = Record<string, never>;
 
 export type PoseType = "stand" | "sit" | "lay" | "floor";
 export type ActionPlaybackMode = "loop" | "once";
+export type AvatarStatus = "Idle" | "Busy" | "Activities" | "Break";
 export type ActionPlayback = {
   mode: ActionPlaybackMode;
   resumeAction?: string;
@@ -16,7 +17,9 @@ export type ActionResult = {
   poseType: PoseType;
   action: string;
   bubble: string;
+  avatarStatus: AvatarStatus;
   log?: string;
+  propId?: string;
 };
 
 export type KichiStaticConfig = {
@@ -43,6 +46,7 @@ export type KichiEnvironmentsConfig = Record<KichiEnvironment, string | null>;
 export type KichiState = {
   currentEnvironment?: KichiEnvironment;
   llmRuntimeEnabled: boolean;
+  testHost?: string;
 };
 
 export type KichiIdentity = {
@@ -84,6 +88,7 @@ export type JoinPayload = {
   botName: string;
   bio: string;
   tags: string[];
+  source: string;
 };
 
 export type JoinAckPayload = {
@@ -117,6 +122,8 @@ export type StatusPayload = {
   bubble: string;
   log: string;
   playback: ActionPlayback;
+  avatarStatus: AvatarStatus;
+  propId?: string;
 };
 
 export type StatusAckPayload = {
@@ -124,9 +131,27 @@ export type StatusAckPayload = {
   requestId: string;
   poseType: PoseType | "";
   action: string;
+  requestedPropId?: string;
   warning?: string;
 };
 
+export type GlanceTarget = "camera";
+
+export type GlancePayload = {
+  type: "kichi_glance";
+  requestId: string;
+  avatarId: string;
+  authKey: string;
+  target: GlanceTarget;
+  duration: number;
+};
+
+export type GlanceAckPayload = {
+  type: "kichi_glance_ack";
+  requestId: string;
+  target: GlanceTarget;
+};
+
 export type HookNotifyType = "message_received" | "before_send_message";
 
 export type HookNotifyPayload = {
@@ -144,12 +169,14 @@ export type IdlePlanStageAction = {
   durationSeconds: number;
   bubble: string;
   log?: string;
+  propId?: string;
 };
 
 export type IdlePlanStage = {
   name: string;
   purpose: string;
   pomodoroPhase: IdlePlanPhase;
+  avatarStatus: AvatarStatus;
   durationSeconds: number;
   actions: IdlePlanStageAction[];
 };
@@ -245,9 +272,7 @@ export type QueryStatusOwnerState = {
   poseType?: string;
   action?: string;
   interactingItemName?: string;
-  desktopActivityCategory?: string;
   desktopAppName?: string;
-  desktopSummary?: string;
 };
 
 export type QueryStatusNote = {
@@ -275,3 +300,33 @@ export type CreateMusicAlbumPayload = {
   albumTitle: string;
   musicTitles: string[];
 };
+
+export type BotMessageHistoryEntry = {
+  from: string;
+  fromName: string;
+  bubble: string;
+};
+
+export type BotMessagePayload = {
+  type: "bot_message";
+  avatarId: string;
+  authKey: string;
+  requestId: string;
+  toAvatarId: string;
+  depth: number;
+  poseType?: PoseType;
+  action?: string;
+  playback?: ActionPlayback;
+  bubble: string;
+  log?: string;
+  history?: BotMessageHistoryEntry[];
+};
+
+export type BotMessageReceivedPayload = {
+  type: "bot_message_received";
+  from: string;
+  fromName: string;
+  depth: number;
+  bubble: string;
+  history?: BotMessageHistoryEntry[];
+};