@yahaha-studio/kichi-forwarder 0.0.1-alpha.28 → 0.0.1-alpha.30

package/{src/album-config.ts → config/album-config.json}

@@ -1,6 +1,4 @@
-import type { Album } from "./types.js";
-
-export const DEFAULT_ALBUM_CONFIG: Album = {
+{
   "albumCount": 10,
   "trackCount": 58,
   "track": [
@@ -508,4 +506,4 @@ export const DEFAULT_ALBUM_CONFIG: Album = {
       ]
     }
   ]
-};
+}

package/index.ts

@@ -2,11 +2,11 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { DEFAULT_ALBUM_CONFIG } from "./src/album-config.js";
 import { parse } from "./src/config.js";
 import { KichiForwarderService } from "./src/service.js";
 import type {
   ActionResult,
+  Album,
   ClockAction,
   ClockConfig,
   KichiRuntimeConfig,
@@ -59,9 +59,12 @@ const RUNTIME_CONFIG_PATH = path.join(KICHI_WORLD_DIR, "kichi-runtime-config.jso
 const LEGACY_SKILLS_CONFIG_PATH = path.join(KICHI_WORLD_DIR, "skills-config.json");
 const IDENTITY_PATH = path.join(KICHI_WORLD_DIR, "identity.json");
 const MAX_NOTEBOARD_TEXT_LENGTH = 200;
+const ALBUM_CONFIG_PATH = new URL("./config/album-config.json", import.meta.url);
+const DEFAULT_ALBUM_CONFIG = loadAlbumConfig();
 const MUSIC_TITLE_LOOKUP = new Map(
   DEFAULT_ALBUM_CONFIG.track.map((item) => [item.name.toLowerCase(), item.name] as const),
 );
+const MUSIC_TITLE_ENUM = DEFAULT_ALBUM_CONFIG.track.map((item) => item.name);
 const MUSIC_TITLE_EXAMPLES = DEFAULT_ALBUM_CONFIG.track.slice(0, 10).map((item) => item.name);
 let cachedConfig: KichiRuntimeConfig | null = null;
 let cachedConfigMtime = 0;
@@ -69,6 +72,36 @@ let cachedConfigPath = "";
 let service: KichiForwarderService | null = null;
 let pluginApi: OpenClawPluginApi | null = null;
 
+function isAlbumConfig(value: unknown): value is Album {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  const config = value as Partial<Album>;
+  return typeof config.albumCount === "number"
+    && typeof config.trackCount === "number"
+    && Array.isArray(config.track)
+    && config.track.every((item) => {
+      if (!item || typeof item !== "object") {
+        return false;
+      }
+      const track = item as Record<string, unknown>;
+      return typeof track.album === "string"
+        && typeof track.name === "string"
+        && Array.isArray(track.tags)
+        && track.tags.every((tag) => typeof tag === "string");
+    });
+}
+
+function loadAlbumConfig(): Album {
+  const raw = fs.readFileSync(ALBUM_CONFIG_PATH, "utf-8");
+  const parsed = JSON.parse(raw) as unknown;
+  if (!isAlbumConfig(parsed)) {
+    throw new Error("Invalid album config at config/album-config.json");
+  }
+  return parsed;
+}
+
 function sanitizeActions(value: unknown, fallback: string[]): string[] {
   if (!Array.isArray(value)) {
     return fallback;
@@ -403,6 +436,20 @@ function normalizeMusicTitles(value: unknown): { titles: string[]; invalidTitles
   return { titles, invalidTitles };
 }
 
+function buildMusicAlbumToolDescription(): string {
+  return [
+    "Create a custom Kichi music album.",
+    "Query status first, then choose track names from the local config/album-config.json that match weather, time, and personality.",
+  ].join("\n");
+}
+
+function buildMusicTitlesDescription(): string {
+  return [
+    "Track names chosen from the local config/album-config.json.",
+    "Use exact names only; the available titles are injected into this tool schema.",
+  ].join(" ");
+}
+
 function buildKichiPrompt(): string {
   return [
     "Kichi App status sync is available via `kichi_action` and `kichi_clock`.",
@@ -426,7 +473,7 @@ function buildKichiPrompt(): string {
     "When to use `kichi_music_album_create`:",
     "- Call `kichi_query_status` first.",
     "- Recommend a variable-length playlist based on weather, time, and your own personality.",
-    "- `albumTitle` is user-defined and `musicTitles` must be exact track names from album-config.",
+    "- `albumTitle` is user-defined and `musicTitles` must be exact track names from the local album-config.json.",
     "",
     "Skip all sync if:",
     "- User says 'don't sync to Kichi' or similar",
@@ -744,7 +791,7 @@ const plugin = {
     api.registerTool({
       name: "kichi_query_status",
       description:
-        "Query Kichi avatar status (notes, weather/time, timer snapshot, and daily note quota). Use this before creating a new note.",
+        "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.",
       parameters: {
         type: "object",
         properties: {
@@ -779,8 +826,7 @@ const plugin = {
 
     api.registerTool({
       name: "kichi_music_album_create",
-      description:
-        "Create a custom Kichi music album. Query status first, then choose track names from album-config that match weather/time and personality.",
+      description: buildMusicAlbumToolDescription(),
       parameters: {
         type: "object",
         properties: {
@@ -794,9 +840,10 @@ const plugin = {
           },
           musicTitles: {
             type: "array",
-            description: "Track names chosen from album-config.",
+            description: buildMusicTitlesDescription(),
             items: {
               type: "string",
+              enum: MUSIC_TITLE_ENUM,
             },
           },
         },
@@ -835,7 +882,7 @@ const plugin = {
           return {
             success: false,
             error: `Unknown musicTitles: ${invalidTitles.join(", ")}`,
-            hint: "Use exact track names from src/album-config.ts",
+            hint: "Use exact track names from config/album-config.json",
             examples: MUSIC_TITLE_EXAMPLES,
           };
         }

package/package.json

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

package/skills/kichi-forwarder/SKILL.md

@@ -233,9 +233,15 @@ Current response includes:
 
 - quota/status fields: `dailyLimit`, `remaining`, `isAvatarInScene`, `environmentWeather`, `environmentTime`, `errorCode`, `errorMessage`
 - 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.
 
-After query, apply `Note Board Policy` and `Note Triage Order` from [references/heartbeat.md](references/heartbeat.md) before deciding whether to post.
+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.
+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.
 
 ### kichi_music_album_create
 
@@ -253,7 +259,7 @@ Parameters:
 
 Track source rule:
 
-- `musicTitles` must use exact track names from `src/album-config.ts` -> `DEFAULT_ALBUM_CONFIG.track[].name`
+- `musicTitles` must use exact track names from `config/album-config.json` -> `track[].name`
 - do not use album names in `musicTitles`
 
 Before create:
@@ -299,7 +305,7 @@ Hard rules:
 
 1. Query first with `kichi_query_status`.
 2. Playlist length is flexible (not fixed), but avoid empty or repetitive selections.
-3. Select tracks from `src/album-config.ts` track name list only.
+3. Select tracks from `config/album-config.json` track name list only.
 4. Recommendation must reflect `environmentWeather` + `environmentTime` + your personality (not random picks).
 5. Use a user-meaningful custom `albumTitle`.
 6. If `kichi_query_status` fails or returns empty/insufficient context, skip creation.

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

@@ -36,10 +36,10 @@ If user wants recurring note board checks:
 - `Meaningful standalone note`: a short non-filler note that adds value to the room (task feeling, world feeling, casual thought, social reaction, or useful context) and is not repetitive.
 - `Standalone trigger`: if `remaining > 0` and no reply target is selected in this run, create 1 standalone note by default (unless 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`, `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`, `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 `timer` progress or note tone to show you pay attention to how the owner is doing (e.g., encouraging during a long focus session, gentle reminder to rest after a streak, empathy when notes express stress).
+  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.
 
 ## Note Triage Order
@@ -76,12 +76,12 @@ Use this exact flow:
 7. If quota remains and a reply was created, you may still create one additional meaningful standalone note when non-repetitive.
 8. Then evaluate non-note status reaction:
 9. If OpenClaw is busy, skip status reaction entirely.
-10. If OpenClaw is idle, use fixed `50%` probability to decide whether to react.
-11. If random hit, call `kichi_action` once. Read the combined context and express the three `Companion intents`:
+10. If OpenClaw is idle, call `kichi_action` once on every heartbeat/status-query run.
+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 `timer` + note tone): 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.
+    - **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 > 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).
+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.
 
 ## HEARTBEAT.md Snippet
@@ -97,11 +97,11 @@ Use this exact flow:
 - Keep each note <= 200 chars.
 - Respect `dailyLimit`, `remaining`.
 - If OpenClaw is busy, skip `kichi_action` reaction.
-- If OpenClaw is idle, use fixed `50%` probability to send one `kichi_action` based on combined context (`notes`, `timer`, `environmentWeather`, `environmentTime`). Express these companion intents:
+- If OpenClaw is idle, send one `kichi_action` on every run based on combined context (`notes`, `ownerState`, `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 timer progress or note tone to show attention to the owner (e.g., encourage during focus, suggest rest after a streak).
+  - **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 > timer state > weather/time.
+- Prioritize signals: owner note > ownerState > 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.
 ```