@yahaha-studio/kichi-forwarder 0.1.2-beta.12 → 0.1.2-beta.14

package/README.md

@@ -12,6 +12,7 @@ It can directly control your companion's avatar in Kichi, show what it is doing,
 
 - Bring your OpenClaw companion into Kichi
 - Directly control the avatar's poses and actions in Kichi
+- Let the avatar briefly glance at the camera when you ask for attention in chat
 - Keep its visible state in sync while it works
 - Plan human-like idle routines during heartbeat windows
 - Let it leave notes for you in Kichi
@@ -36,6 +37,7 @@ Get the `host` and `avatarId` from Kichi, then use them with `kichi_switch_host`
 
 - Connect to your chosen Kichi host and stay in sync while it works
 - Directly control the Kichi avatar's poses and actions
+- Briefly glance toward the camera when you directly ask from chat
 - Show activity in Kichi with actions, bubbles, logs, and timers
 - Leave notes for you on Kichi note boards
 - Recommend music in Kichi as part of your daily routine

package/dist/index.js

@@ -38,6 +38,7 @@ 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 DEFAULT_GLANCE_DURATION_SECONDS = 1.8;
 const IDLE_PLAN_POMODORO_PHASES = ["focus", "shortBreak", "longBreak", "none"];
 let cachedStaticConfig = null;
 let cachedStaticConfigMtime = 0;
@@ -814,7 +815,7 @@ function buildKichiActionDescription(service) {
     const roomContext = service?.getCachedRoomContext();
     const poseableProps = roomContext?.PoseableProps;
     if (Array.isArray(poseableProps) && poseableProps.length > 0) {
-        lines.push("", "Cached RoomContext.PoseableProps (from last kichi_query_status):", JSON.stringify(poseableProps), "When using a sit or lay pose, pick the propId whose DisplayName best matches the current task context and whose OccupancyState is not fully_occupied. If no prop fits, omit propId.");
+        lines.push("", "Cached RoomContext.PoseableProps (from last kichi_query_status):", JSON.stringify(poseableProps), "When using a sit or lay pose, pick the propId whose PoseableProps information best matches the current task context and whose OccupancyState is not fully_occupied. If no prop fits, omit propId.");
     }
     return lines.join("\n");
 }
@@ -961,6 +962,10 @@ const plugin = {
                         description: "Optional list of OpenClaw self-perceived personality tags",
                         items: { type: "string" },
                     },
+                    source: {
+                        type: "string",
+                        description: "Optional join source identifier. Defaults to Kichi World join-source.json, then openclaw.",
+                    },
                 },
                 required: ["botName", "bio"],
             },
@@ -974,6 +979,7 @@ const plugin = {
                 let avatarId = params?.avatarId;
                 const botName = params?.botName?.trim();
                 const bio = params?.bio?.trim();
+                const rawSource = params?.source;
                 const { tags, error: tagsError } = normalizeJoinTags(params?.tags);
                 if (!avatarId) {
                     avatarId = service.readSavedAvatarId() ?? undefined;
@@ -987,10 +993,22 @@ const plugin = {
                 if (!bio) {
                     return jsonResult({ success: false, error: "No bio" });
                 }
+                let source;
+                try {
+                    source = rawSource === undefined
+                        ? service.readConfiguredJoinSource() ?? "openclaw"
+                        : trimOptionalString(rawSource);
+                }
+                catch (err) {
+                    return jsonResult({ success: false, error: err instanceof Error ? err.message : String(err) });
+                }
+                if (!source) {
+                    return jsonResult({ success: false, error: "source must be a non-empty string" });
+                }
                 if (tagsError) {
                     return jsonResult({ success: false, error: tagsError });
                 }
-                const result = await service.join(avatarId, botName, bio, tags ?? []);
+                const result = await service.join(avatarId, botName, bio, tags ?? [], source);
                 if (result.success) {
                     return jsonResult({ success: true, authKey: result.authKey });
                 }
@@ -1221,6 +1239,59 @@ const plugin = {
                 },
             });
         }, { name: "kichi_action" });
+        api.registerTool((ctx) => ({
+            name: "kichi_glance",
+            label: "kichi_glance",
+            description: "Ask the Kichi avatar to briefly look at the camera. Use only for direct player chat requests such as \"look at me\" or \"look at the camera\". Do not use for heartbeat, idle planning, bot-to-bot messages, lifecycle hooks, or routine work/status sync.",
+            parameters: {
+                type: "object",
+                properties: {
+                    requestId: {
+                        type: "string",
+                        description: "Optional client request ID for tracing. The websocket ack returns this ID.",
+                    },
+                    target: {
+                        type: "string",
+                        enum: ["camera"],
+                        description: "Glance target. The only supported target is camera.",
+                    },
+                    duration: {
+                        type: "number",
+                        description: "Optional glance duration in seconds. Defaults to 1.8.",
+                    },
+                },
+            },
+            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 { requestId, target, duration } = (params || {});
+                if (requestId !== undefined && typeof requestId !== "string") {
+                    return jsonResult({ success: false, error: "requestId must be a string when provided" });
+                }
+                const normalizedTarget = target === undefined ? "camera" : target;
+                if (normalizedTarget !== "camera") {
+                    return jsonResult({ success: false, error: "target must be camera" });
+                }
+                const normalizedDuration = duration === undefined ? DEFAULT_GLANCE_DURATION_SECONDS : duration;
+                if (typeof normalizedDuration !== "number" || !Number.isFinite(normalizedDuration) || normalizedDuration <= 0) {
+                    return jsonResult({ success: false, error: "duration must be a positive finite number" });
+                }
+                if (!service.hasValidIdentity() || !service.isConnected()) {
+                    return jsonResult({ success: false, error: "Not connected to Kichi world" });
+                }
+                try {
+                    const ack = await service.sendGlance("camera", normalizedDuration, typeof requestId === "string" ? requestId : undefined);
+                    return jsonResult({ success: true, ...ack });
+                }
+                catch (error) {
+                    return jsonResult({ success: false, error: `Failed to send glance: ${error}` });
+                }
+            },
+        }), { name: "kichi_glance" });
         api.registerTool((ctx) => ({
             name: "kichi_idle_plan",
             label: "kichi_idle_plan",
@@ -1449,7 +1520,7 @@ const plugin = {
         api.registerTool((ctx) => ({
             name: "kichi_query_status",
             label: "kichi_query_status",
-            description: "Query Kichi room and avatar status — includes room personnel, notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, `hasCreatedMusicAlbumToday`, and RoomContext.PoseableProps (poseable props with PropId, DisplayName, SupportedPoseTypes, OccupancyState). The PoseableProps list is cached internally so that kichi_action can reference a propId during regular work sync without re-querying. Use this when the user asks to check kichi status, room status, or who is in the room. Also use this before creating a new note or daily recommended music album. For heartbeat planning, use the returned idlePlan as reference when shaping the next idle plan.",
+            description: "Query Kichi room and avatar status — includes room personnel, notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, `hasCreatedMusicAlbumToday`, and RoomContext.PoseableProps (poseable props with PropId, DisplayName, Description, SupportedPoseTypes, OccupancyState). The PoseableProps list is cached internally so that kichi_action can reference a propId during regular work sync without re-querying. Use this when the user asks to check kichi status, room status, or who is in the room. Also use this before creating a new note or daily recommended music album. For heartbeat planning, use the returned idlePlan as reference when shaping the next idle plan.",
             parameters: {
                 type: "object",
                 properties: {

package/dist/src/service.js

@@ -4,6 +4,8 @@ import * as path from "path";
 import { randomUUID } from "node:crypto";
 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";
 export class KichiForwarderService {
     logger;
     options;
@@ -63,7 +65,7 @@ export class KichiForwarderService {
         }
         return this.getConnectionStatus();
     }
-    async join(avatarId, botName, bio, tags) {
+    async join(avatarId, botName, bio, tags, source) {
         if (!this.host) {
             return { success: false, error: "No Kichi host configured. Run kichi_switch_host first." };
         }
@@ -78,7 +80,7 @@ export class KichiForwarderService {
             this.identity = { avatarId };
             this.saveIdentity();
             this.joinResolve = resolve;
-            const payload = { type: "join", avatarId, botName, bio, tags };
+            const payload = { type: "join", avatarId, botName, bio, tags, source };
             const sendJoin = () => this.ws?.send(JSON.stringify(payload));
             if (this.ws?.readyState === WebSocket.OPEN) {
                 sendJoin();
@@ -176,6 +178,30 @@ export class KichiForwarderService {
         this.ws.send(JSON.stringify(payload));
         return true;
     }
+    async sendGlance(target, durationSeconds = DEFAULT_GLANCE_DURATION_SECONDS, requestId) {
+        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 = {
+            type: "kichi_glance",
+            requestId: requestId?.trim() || randomUUID(),
+            avatarId: identity.avatarId,
+            authKey: identity.authKey,
+            target,
+            duration: durationSeconds,
+        };
+        return this.sendRequest(payload, "kichi_glance_ack", 5000);
+    }
     async queryStatus(requestId) {
         const identity = this.requireIdentity();
         if (!identity) {
@@ -274,6 +300,24 @@ export class KichiForwarderService {
     getRuntimeDir() {
         return this.options.runtimeDir;
     }
+    getJoinSourcePath() {
+        return path.join(this.getKichiWorldRootDir(), JOIN_SOURCE_FILE_NAME);
+    }
+    readConfiguredJoinSource() {
+        const sourcePath = this.getJoinSourcePath();
+        if (!fs.existsSync(sourcePath)) {
+            return null;
+        }
+        const data = JSON.parse(fs.readFileSync(sourcePath, "utf-8"));
+        if (!data || typeof data !== "object" || Array.isArray(data)) {
+            throw new Error(`${JOIN_SOURCE_FILE_NAME} must contain a JSON object`);
+        }
+        const source = data.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() {
         return path.join(this.options.runtimeDir, "state.json");
     }
@@ -621,6 +665,9 @@ export class KichiForwarderService {
         }
         return path.join(this.options.runtimeDir, "hosts", encodeURIComponent(this.host));
     }
+    getKichiWorldRootDir() {
+        return path.dirname(path.dirname(this.options.runtimeDir));
+    }
     getWsUrl() {
         if (!this.host) {
             throw new Error("No Kichi host configured");

package/index.ts

@@ -60,6 +60,7 @@ 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 DEFAULT_GLANCE_DURATION_SECONDS = 1.8;
 const IDLE_PLAN_POMODORO_PHASES = ["focus", "shortBreak", "longBreak", "none"] as const;
 let cachedStaticConfig: KichiStaticConfig | null = null;
 let cachedStaticConfigMtime = 0;
@@ -1014,7 +1015,7 @@ function buildKichiActionDescription(service?: KichiForwarderService): string {
       "",
       "Cached RoomContext.PoseableProps (from last kichi_query_status):",
       JSON.stringify(poseableProps),
-      "When using a sit or lay pose, pick the propId whose DisplayName best matches the current task context and whose OccupancyState is not fully_occupied. If no prop fits, omit propId.",
+      "When using a sit or lay pose, pick the propId whose PoseableProps information best matches the current task context and whose OccupancyState is not fully_occupied. If no prop fits, omit propId.",
     );
   }
 
@@ -1179,6 +1180,10 @@ const plugin = {
             description: "Optional list of OpenClaw self-perceived personality tags",
             items: { type: "string" },
           },
+          source: {
+            type: "string",
+            description: "Optional join source identifier. Defaults to Kichi World join-source.json, then openclaw.",
+          },
         },
         required: ["botName", "bio"],
       },
@@ -1192,6 +1197,7 @@ const plugin = {
         let avatarId = (params as { avatarId?: string } | null)?.avatarId;
         const botName = (params as { botName?: string } | null)?.botName?.trim();
         const bio = (params as { bio?: string } | null)?.bio?.trim();
+        const rawSource = (params as { source?: unknown } | null)?.source;
         const { tags, error: tagsError } = normalizeJoinTags(
           (params as { tags?: unknown } | null)?.tags,
         );
@@ -1207,10 +1213,21 @@ const plugin = {
         if (!bio) {
           return jsonResult({ success: false, error: "No bio" });
         }
+        let source: string | null | undefined;
+        try {
+          source = rawSource === undefined
+            ? service.readConfiguredJoinSource() ?? "openclaw"
+            : trimOptionalString(rawSource);
+        } catch (err) {
+          return jsonResult({ success: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        if (!source) {
+          return jsonResult({ success: false, error: "source must be a non-empty string" });
+        }
         if (tagsError) {
           return jsonResult({ success: false, error: tagsError });
         }
-        const result = await service.join(avatarId, botName, bio, tags ?? []);
+        const result = await service.join(avatarId, botName, bio, tags ?? [], source);
         if (result.success) {
           return jsonResult({ success: true, authKey: result.authKey });
         }
@@ -1462,6 +1479,71 @@ const plugin = {
         });
       },
     })}, { name: "kichi_action" });
+
+    api.registerTool((ctx) => ({
+      name: "kichi_glance",
+      label: "kichi_glance",
+      description:
+        "Ask the Kichi avatar to briefly look at the camera. Use only for direct player chat requests such as \"look at me\" or \"look at the camera\". Do not use for heartbeat, idle planning, bot-to-bot messages, lifecycle hooks, or routine work/status sync.",
+      parameters: {
+        type: "object",
+        properties: {
+          requestId: {
+            type: "string",
+            description: "Optional client request ID for tracing. The websocket ack returns this ID.",
+          },
+          target: {
+            type: "string",
+            enum: ["camera"],
+            description: "Glance target. The only supported target is camera.",
+          },
+          duration: {
+            type: "number",
+            description: "Optional glance duration in seconds. Defaults to 1.8.",
+          },
+        },
+      },
+      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 { requestId, target, duration } = (params || {}) as {
+          requestId?: unknown;
+          target?: unknown;
+          duration?: unknown;
+        };
+
+        if (requestId !== undefined && typeof requestId !== "string") {
+          return jsonResult({ success: false, error: "requestId must be a string when provided" });
+        }
+        const normalizedTarget = target === undefined ? "camera" : target;
+        if (normalizedTarget !== "camera") {
+          return jsonResult({ success: false, error: "target must be camera" });
+        }
+        const normalizedDuration = duration === undefined ? DEFAULT_GLANCE_DURATION_SECONDS : duration;
+        if (typeof normalizedDuration !== "number" || !Number.isFinite(normalizedDuration) || normalizedDuration <= 0) {
+          return jsonResult({ success: false, error: "duration must be a positive finite number" });
+        }
+        if (!service.hasValidIdentity() || !service.isConnected()) {
+          return jsonResult({ success: false, error: "Not connected to Kichi world" });
+        }
+
+        try {
+          const ack = await service.sendGlance(
+            "camera",
+            normalizedDuration,
+            typeof requestId === "string" ? requestId : undefined,
+          );
+          return jsonResult({ success: true, ...ack });
+        } catch (error) {
+          return jsonResult({ success: false, error: `Failed to send glance: ${error}` });
+        }
+      },
+    }), { name: "kichi_glance" });
+
     api.registerTool((ctx) => ({
       name: "kichi_idle_plan",
       label: "kichi_idle_plan",
@@ -1701,7 +1783,7 @@ const plugin = {
       name: "kichi_query_status",
       label: "kichi_query_status",
       description:
-        "Query Kichi room and avatar status — includes room personnel, notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, `hasCreatedMusicAlbumToday`, and RoomContext.PoseableProps (poseable props with PropId, DisplayName, SupportedPoseTypes, OccupancyState). The PoseableProps list is cached internally so that kichi_action can reference a propId during regular work sync without re-querying. Use this when the user asks to check kichi status, room status, or who is in the room. Also use this before creating a new note or daily recommended music album. For heartbeat planning, use the returned idlePlan as reference when shaping the next idle plan.",
+        "Query Kichi room and avatar status — includes room personnel, notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, `hasCreatedMusicAlbumToday`, and RoomContext.PoseableProps (poseable props with PropId, DisplayName, Description, SupportedPoseTypes, OccupancyState). The PoseableProps list is cached internally so that kichi_action can reference a propId during regular work sync without re-querying. Use this when the user asks to check kichi status, room status, or who is in the room. Also use this before creating a new note or daily recommended music album. For heartbeat planning, use the returned idlePlan as reference when shaping the next idle plan.",
       parameters: {
         type: "object",
         properties: {
@@ -1979,4 +2061,3 @@ const plugin = {
 };
 
 export default plugin;
-

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.12",
+  "version": "0.1.2-beta.14",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
   "contracts": {
@@ -13,6 +13,7 @@
       "kichi_leave",
       "kichi_connection_status",
       "kichi_action",
+      "kichi_glance",
       "kichi_idle_plan",
       "kichi_clock",
       "kichi_query_status",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.1.2-beta.12",
+  "version": "0.1.2-beta.14",
   "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

@@ -74,7 +74,7 @@ Use this order unless the user asks for a different explicit action. For install
 3. If the requested `avatarId` differs from the current host's connected `avatarId`, call `kichi_leave` first when the old avatar is still joined, then call `kichi_join` with the requested `avatarId`.
 4. If no `authKey` is available, call `kichi_join`.
 5. If `authKey` exists but websocket is not open, call `kichi_rejoin` or wait for automatic reconnect and rejoin.
-6. Use `kichi_action`, `kichi_clock`, note board tools, and music album tools after status is ready.
+6. Use `kichi_action`, `kichi_glance`, `kichi_clock`, note board tools, and music album tools after status is ready.
 
 ## Tools
 
@@ -141,6 +141,19 @@ Use this for direct Kichi avatar control as well as lifecycle sync.
 - For most work, prefer a sit pose and switch actions inside the same task as the work moves between stages.
 - The current action lists are injected into prompt context before the model chooses `kichi_action`.
 
+### kichi_glance
+
+```text
+kichi_glance(target: "camera", duration: 1.8)
+```
+
+Use this only when the player directly asks from chat for attention such as "look at me" or "look at the camera".
+
+- `target`: optional. Only `camera` is supported.
+- `duration`: optional seconds, defaults to `1.8`.
+- `requestId`: optional tracing ID; the websocket ack returns it.
+- Do not use this for heartbeat, idle plans, bot messages, lifecycle hooks, or routine work/status sync.
+
 ### kichi_idle_plan
 
 Use this for the avatar's heartbeat idle plan.

package/src/service.ts

@@ -13,6 +13,9 @@ import type {
   ClockPayload,
   CreateMusicAlbumPayload,
   CreateNotesBoardNotePayload,
+  GlanceAckPayload,
+  GlancePayload,
+  GlanceTarget,
   HookNotifyPayload,
   HookNotifyType,
   IdlePlanContent,
@@ -33,6 +36,8 @@ 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";
 
 type AckFailureResult = {
   success: false;
@@ -138,6 +143,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." };
@@ -153,7 +159,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();
@@ -262,6 +268,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) {
@@ -381,6 +417,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");
   }
@@ -765,6 +824,10 @@ export class KichiForwarderService {
     return path.join(this.options.runtimeDir, "hosts", encodeURIComponent(this.host));
   }
 
+  private getKichiWorldRootDir(): string {
+    return path.dirname(path.dirname(this.options.runtimeDir));
+  }
+
   private getWsUrl(): string {
     if (!this.host) {
       throw new Error("No Kichi host configured");

package/src/types.ts

@@ -86,6 +86,7 @@ export type JoinPayload = {
   botName: string;
   bio: string;
   tags: string[];
+  source: string;
 };
 
 export type JoinAckPayload = {
@@ -131,6 +132,23 @@ export type StatusAckPayload = {
   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 = {