@yahaha-studio/kichi-forwarder 0.0.1-alpha.55 → 0.1.0-beta.1

package/README.md

@@ -0,0 +1,72 @@
+# Kichi Forwarder
+
+![Kichi cover](./assets/kichi-cover.jpg)
+
+Kichi Forwarder brings your OpenClaw companion into Kichi.
+
+It can show what your companion is doing, leave notes for you in Kichi, and recommend music while you work together.
+
+> The world of Kichi opens for playtest soon.
+
+## Highlights
+
+- Bring your OpenClaw companion into Kichi
+- Keep its visible state in sync while it works
+- Let it leave notes for you in Kichi
+- Let it recommend music in Kichi
+
+## Install
+
+Install from ClawHub:
+
+```bash
+openclaw plugins install clawhub:@yahaha-studio/kichi-forwarder
+```
+
+Install with the bare package name:
+
+```bash
+openclaw plugins install @yahaha-studio/kichi-forwarder
+```
+
+For bare package installs, OpenClaw tries ClawHub first and falls back to npm automatically.
+
+## Get Started in Kichi
+
+Kichi provides the install command and the connection details you need to connect a companion.
+
+Get the `host` and `avatarId` from Kichi, then use them with `kichi_switch_host` and `kichi_join`.
+
+## What Your Companion Can Do
+
+- Connect to your chosen Kichi host and stay in sync while it works
+- 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
+- React based on your current Kichi status before posting notes or music
+
+## Quick Setup
+
+1. Install the plugin.
+2. Start OpenClaw with the plugin enabled.
+3. Use `kichi_switch_host` and `kichi_join` to connect your companion to Kichi.
+4. Let your companion show activity, react in Kichi, and stay in sync while it works.
+5. Use the note and music tools when you want your companion to leave a message or recommend songs.
+
+## Runtime State
+
+The plugin stores runtime state in the OpenClaw user directory:
+
+- Windows: `%USERPROFILE%\.openclaw\kichi-world\`
+- Linux/macOS: `~/.openclaw/kichi-world/`
+
+Important files:
+
+- `state.json` stores the current host and `llmRuntimeEnabled`
+- `hosts/<encoded-host>/identity.json` stores host-specific `avatarId` and `authKey`
+
+## Notes
+
+- This plugin runs inside OpenClaw and adds Kichi-specific companion behaviors.
+- Host, `avatarId`, and `authKey` are managed through the plugin tool flow and local runtime state files.
+- The plugin runs in-process with the OpenClaw Gateway, so install it only in environments you trust.

package/index.ts

@@ -10,7 +10,6 @@ import type {
   Album,
   ClockAction,
   ClockConfig,
-  KichiForwarderConfig,
   KichiState,
   KichiStaticConfig,
   PomodoroPhase,
@@ -124,19 +123,18 @@ function normalizeStaticConfig(value: unknown): KichiStaticConfig {
 function readState(): KichiState {
   if (!fs.existsSync(STATE_PATH)) {
     return {
-      currentHost: "focus.yahaha.com",
       llmRuntimeEnabled: DEFAULT_LLM_RUNTIME_ENABLED,
     };
   }
   const data = JSON.parse(fs.readFileSync(STATE_PATH, "utf-8")) as Partial<KichiState>;
-  if (typeof data.currentHost !== "string" || !data.currentHost.trim()) {
+  if (data.currentHost !== undefined && (typeof data.currentHost !== "string" || !data.currentHost.trim())) {
     throw new Error(`Invalid currentHost in ${STATE_PATH}`);
   }
   if (typeof data.llmRuntimeEnabled !== "boolean") {
     throw new Error(`Invalid llmRuntimeEnabled in ${STATE_PATH}`);
   }
   return {
-    currentHost: data.currentHost,
+    ...(typeof data.currentHost === "string" ? { currentHost: data.currentHost } : {}),
     llmRuntimeEnabled: data.llmRuntimeEnabled,
   };
 }
@@ -606,10 +604,8 @@ const plugin = {
     api.registerService({
       id: "kichi-forwarder",
       start: (ctx) => {
-        const cfg = parse(
-          ctx.config.plugins?.entries?.["kichi-forwarder"]?.config,
-        ) as KichiForwarderConfig;
-        service = new KichiForwarderService(cfg, api.logger);
+        parse(ctx.config.plugins?.entries?.["kichi-forwarder"]?.config);
+        service = new KichiForwarderService(api.logger);
         return service.start();
       },
       stop: () => service?.stop(),
@@ -685,7 +681,7 @@ const plugin = {
         properties: {
           host: {
             type: "string",
-            description: "Target Kichi host, for example focus.yahaha.com or 127.0.0.1",
+            description: "Target Kichi host, for example your.kichi.host or 127.0.0.1",
           },
         },
         required: ["host"],

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "id": "kichi-forwarder",
   "name": "Kichi Forwarder",
-  "description": "Sync agent lifecycle/status to Kichi world and provide Kichi timer/noteboard tools",
-  "version": "0.0.1",
+  "description": "Native OpenClaw plugin for Kichi World with status sync, timers, notes, and music tools",
+  "version": "0.1.0-beta.1",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
   "configSchema": {

package/package.json

@@ -1,24 +1,40 @@
-{
-  "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.0.1-alpha.55",
-  "description": "Forward OpenClaw agent events to external WebSocket server for visualization",
-  "type": "module",
-  "main": "index.ts",
-  "openclaw": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "publishConfig": {
-    "access": "public",
-    "tag": "alpha"
-  },
-  "dependencies": {
-    "ws": "^8.19.0"
-  },
-  "devDependencies": {
-    "@types/node": "^24.3.0",
-    "@types/ws": "^8.18.1",
-    "openclaw": "*"
-  }
-}
+{
+  "name": "@yahaha-studio/kichi-forwarder",
+  "version": "0.1.0-beta.1",
+  "description": "Native OpenClaw plugin for Kichi World with status sync, timers, notes, and music tools",
+  "type": "module",
+  "main": "index.ts",
+  "files": [
+    "README.md",
+    "assets/",
+    "config/",
+    "index.ts",
+    "openclaw.plugin.json",
+    "skills/",
+    "src/"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.24",
+      "minGatewayVersion": "2026.3.24"
+    },
+    "build": {
+      "openclawVersion": "2026.3.24",
+      "pluginSdkVersion": "2026.3.24"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "@types/ws": "^8.18.1",
+    "openclaw": "2026.3.24"
+  }
+}

package/skills/kichi-forwarder/SKILL.md

@@ -1,26 +1,25 @@
 ---
 name: kichi-forwarder
 description: Use Kichi websocket tools for proactive task lifecycle sync (start/switch/milestone/end), activity updates, timer control, and note board workflows; prioritize explicit user Kichi requests and skip sync when the user opts out.
-metadata: {"openclaw":{"skillKey":"kichi-forwarder","homepage":"https://github.com/XiaoxinShi001/yahaha_focus_forwarder_alpha"}}
+metadata: {"openclaw":{"skillKey":"kichi-forwarder","homepage":"https://github.com/Yahaha-Studio/kichi-forwarder"}}
 ---
 
 # Kichi Forwarder
 
-Sync OpenClaw status to Kichi World and operate Kichi note boards through websocket tools.
+Kichi Forwarder provides websocket tools for connecting an OpenClaw agent to Kichi, syncing companion status, and handling Kichi notes, timers, and music workflows.
 
 ## Skill Files (Absolute URLs)
 
 If this skill is loaded from a remote URL before local installation, use these files:
 
-- `SKILL.md`: `https://xiaoxinshi001.github.io/yahaha_focus_forwarder_alpha/SKILL.md`
-- `install.md`: `https://xiaoxinshi001.github.io/yahaha_focus_forwarder_alpha/references/install.md`
-- `error.md`: `https://xiaoxinshi001.github.io/yahaha_focus_forwarder_alpha/references/error.md`
-- `heartbeat.md`: `https://xiaoxinshi001.github.io/yahaha_focus_forwarder_alpha/references/heartbeat.md`
+- `SKILL.md`: `https://yahaha-studio.github.io/kichi-forwarder/SKILL.md`
+- `install.md`: `https://yahaha-studio.github.io/kichi-forwarder/references/install.md`
+- `error.md`: `https://yahaha-studio.github.io/kichi-forwarder/references/error.md`
+- `heartbeat.md`: `https://yahaha-studio.github.io/kichi-forwarder/references/heartbeat.md`
 
 ## Host Rules
 
-- If the user explicitly includes `host: <value>`, use that host.
-- If the user does not specify a host, use `focus.yahaha.com`.
+- Install and connect requests include `host: <value>`.
 
 ## Runtime State
 
@@ -33,13 +32,13 @@ Runtime data lives under the user home directory:
 
 When this skill is loaded from:
 
-- `https://xiaoxinshi001.github.io/yahaha_focus_forwarder_alpha/SKILL.md`
+- `https://yahaha-studio.github.io/kichi-forwarder/SKILL.md`
 
-and the user asks to connect/install with `avatarId` and optional `host`, do not invent a separate install flow in this file.
+and the user asks to connect/install with `avatarId` and `host`, do not invent a separate install flow in this file.
 
 The install and join flow is defined only in:
 
-- `https://xiaoxinshi001.github.io/yahaha_focus_forwarder_alpha/references/install.md`
+- `https://yahaha-studio.github.io/kichi-forwarder/references/install.md`
 
 Read and follow that file before any tool call.
 
@@ -85,7 +84,7 @@ kichi_join(avatarId: "your-avatar-id", botName: "<from IDENTITY.md>", bio: "<fro
 ### kichi_switch_host
 
 ```text
-kichi_switch_host(host: "focus.yahaha.com")
+kichi_switch_host(host: "your.kichi.host")
 ```
 
 - `host`: required

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

@@ -1,10 +1,11 @@
 # Install Error Handling
 
-If `openclaw plugins install @yahaha-studio/kichi-forwarder@latest` fails, read the error output carefully. Common causes and fixes:
+If `openclaw plugins install clawhub:@yahaha-studio/kichi-forwarder` fails, read the error output carefully. Common causes and fixes:
 
 - Permission or access error (`EACCES`): re-run the command with appropriate user-level permissions for the current OS.
-- npm spawn error (`ENOENT`, `spawn npm`): verify that Node.js (v18+) and npm are installed and available in PATH. On Windows, confirm `where.exe npm` returns a valid path.
+- Package resolution or visibility error: confirm the package name is exactly `@yahaha-studio/kichi-forwarder` and that the package is published and publicly available on ClawHub.
+- Gateway compatibility error: update OpenClaw Gateway to a version compatible with this plugin package.
 - File conflict (`EEXIST`): re-run the install command with `--force`.
 - Network or registry error: check internet connectivity and retry.
 
-After applying the fix, re-run `openclaw plugins install @yahaha-studio/kichi-forwarder@latest`.
+After applying the fix, re-run `openclaw plugins install clawhub:@yahaha-studio/kichi-forwarder`.

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

@@ -1,9 +1,8 @@
-# Install
+# Install
 
 ## Host Rules
 
-- If the user explicitly includes `host: <value>`, use that host.
-- If the user does not specify a host, use `focus.yahaha.com`.
+- Install and connect requests include `host: <value>`.
 
 ## Runtime Files
 
@@ -14,7 +13,7 @@ Persist runtime state to `state.json`:
 
 ```json
 {
-  "currentHost": "focus.yahaha.com",
+  "currentHost": "your.kichi.host",
   "llmRuntimeEnabled": true
 }
 ```
@@ -33,23 +32,15 @@ Save `avatarId` to the host-specific `identity.json` before using `kichi_join`:
 ## Install
 
 ```bash
-openclaw plugins install @yahaha-studio/kichi-forwarder@latest
+openclaw plugins install clawhub:@yahaha-studio/kichi-forwarder
 ```
 
 ## Remote URL Install Command Path (Non-skippable)
 
 If the user asks:
 
-- Default:
-
-```text
-Read https://xiaoxinshi001.github.io/yahaha_focus_forwarder_alpha/SKILL.md and connect me to Kichi World with avatarId: {avatarId}
-```
-
-- With explicit host:
-
 ```text
-Read https://xiaoxinshi001.github.io/yahaha_focus_forwarder_alpha/SKILL.md and connect me to Kichi World with avatarId: {avatarId} and host: {host}
+Read https://yahaha-studio.github.io/kichi-forwarder/SKILL.md and connect me to Kichi World with avatarId: {avatarId} and host: {host}
 ```
 
 ## Command Execution Flow
@@ -59,7 +50,7 @@ When the user asks with one of the commands above, execute in this fixed order:
 1. Read `install.md` and `heartbeat.md` from the published skill URLs before any tool call.
 2. Parse `avatarId` from user text (`AvatarId`/`avatarId`, case-insensitive).
 3. Resolve the host and write `state.json`.
-4. Run `openclaw plugins install @yahaha-studio/kichi-forwarder@latest`.
+4. Run `openclaw plugins install clawhub:@yahaha-studio/kichi-forwarder`.
 5. Ensure the plugin is installed and enabled.
 6. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Gate` from [heartbeat.md](heartbeat.md).
 7. If `HEARTBEAT.md` was not updated successfully, report setup as incomplete and stop immediately. Do not continue to `kichi_status` or `kichi_join`.

package/src/config.ts

@@ -1,8 +1,6 @@
 import type { KichiForwarderConfig } from "./types.js";
 
-const FIXED_CONFIG: KichiForwarderConfig = {
-  defaultHost: "focus.yahaha.com",
-};
+const FIXED_CONFIG: KichiForwarderConfig = {};
 
 export function parse(_value: unknown): KichiForwarderConfig {
   return FIXED_CONFIG;

package/src/service.ts

@@ -15,7 +15,6 @@ import type {
   JoinAckPayload,
   JoinPayload,
   KichiConnectionStatus,
-  KichiForwarderConfig,
   KichiIdentity,
   KichiState,
   LeaveAckPayload,
@@ -56,7 +55,7 @@ export class KichiForwarderService {
   private stopped = false;
   private reconnectTimeout: NodeJS.Timeout | null = null;
   private identity: KichiIdentity | null = null;
-  private host: string;
+  private host: string | null = null;
   private joinResolve: ((result: JoinResult) => void) | null = null;
   private pendingRequests = new Map<
     string,
@@ -68,15 +67,17 @@ export class KichiForwarderService {
     }
   >();
 
-  constructor(private config: KichiForwarderConfig, private logger: Logger) {
-    this.host = config.defaultHost;
-  }
+  constructor(private logger: Logger) {}
 
   async start(): Promise<void> {
     this.host = this.loadCurrentHost();
-    this.identity = this.loadIdentity();
+    this.identity = this.host ? this.loadIdentity() : null;
     this.stopped = false;
-    this.connect();
+    if (this.host) {
+      this.connect();
+      return;
+    }
+    this.logger.info("Kichi host is not configured yet; waiting for kichi_switch_host");
   }
 
   async stop(): Promise<void> {
@@ -107,6 +108,9 @@ export class KichiForwarderService {
     bio: string,
     tags: string[],
   ): Promise<JoinResult> {
+    if (!this.host) {
+      return { success: false, error: "No Kichi host configured. Run kichi_switch_host first." };
+    }
     return new Promise((resolve) => {
       this.identity = { avatarId };
       this.saveIdentity();
@@ -251,14 +255,20 @@ export class KichiForwarderService {
   hasValidIdentity(): boolean { return !!this.identity?.avatarId && !!this.identity?.authKey; }
 
   getCurrentHost(): string {
-    return this.host;
+    return this.host ?? "";
   }
 
   getIdentityPath(): string {
+    if (!this.host) {
+      return "";
+    }
     return path.join(this.getIdentityDir(), "identity.json");
   }
 
   readSavedAvatarId(): string | null {
+    if (!this.host) {
+      return null;
+    }
     return this.loadIdentity()?.avatarId ?? null;
   }
 
@@ -267,7 +277,9 @@ export class KichiForwarderService {
       return {
         accepted: false,
         mode: "unavailable",
-        message: "Missing authKey. Run kichi_join first.",
+        message: this.host
+          ? "Missing authKey. Run kichi_join first."
+          : "No Kichi host configured. Run kichi_switch_host first.",
       };
     }
 
@@ -306,10 +318,14 @@ export class KichiForwarderService {
   }
 
   getConnectionStatus(): KichiConnectionStatus {
+    const host = this.host ?? undefined;
     return {
-      host: this.host,
-      wsUrl: this.getWsUrl(),
-      identityPath: this.getIdentityPath(),
+      ...(host ? {
+        host,
+        wsUrl: this.getWsUrl(),
+        identityPath: this.getIdentityPath(),
+      } : {}),
+      hostConfigured: !!host,
       connected: this.isConnected(),
       websocketState: this.getWebsocketState(),
       hasIdentity: !!this.identity?.avatarId,
@@ -355,7 +371,7 @@ export class KichiForwarderService {
   }
 
   private connect(): void {
-    if (this.stopped) return;
+    if (this.stopped || !this.host) return;
 
     const wsUrl = this.getWsUrl();
     const ws = new WebSocket(wsUrl);
@@ -523,6 +539,9 @@ export class KichiForwarderService {
   }
 
   private loadIdentity(): KichiIdentity | null {
+    if (!this.host) {
+      return null;
+    }
     try {
       const identityPath = this.getIdentityPath();
       if (!fs.existsSync(identityPath)) return null;
@@ -542,7 +561,7 @@ export class KichiForwarderService {
   }
 
   private saveIdentity(): void {
-    if (!this.identity?.avatarId) return;
+    if (!this.identity?.avatarId || !this.host) return;
     try {
       const identityDir = this.getIdentityDir();
       const identityPath = this.getIdentityPath();
@@ -590,10 +609,16 @@ export class KichiForwarderService {
   }
 
   private getIdentityDir(): string {
+    if (!this.host) {
+      throw new Error("No Kichi host configured");
+    }
     return path.join(HOSTS_DIR, encodeURIComponent(this.host));
   }
 
   private getWsUrl(): string {
+    if (!this.host) {
+      throw new Error("No Kichi host configured");
+    }
     const protocol = this.isPlainIpHost(this.host) || this.host === "localhost" ? "ws" : "wss";
     return `${protocol}://${this.host}:48870/ws/openclaw`;
   }
@@ -604,11 +629,10 @@ export class KichiForwarderService {
       || /^[0-9a-f:]+$/i.test(host);
   }
 
-  private loadCurrentHost(): string {
+  private loadCurrentHost(): string | null {
     try {
       if (!fs.existsSync(STATE_PATH)) {
-        this.persistCurrentHost(this.config.defaultHost);
-        return this.config.defaultHost;
+        return null;
       }
       const data = JSON.parse(fs.readFileSync(STATE_PATH, "utf-8")) as { currentHost?: unknown };
       if (typeof data.currentHost === "string" && data.currentHost.trim()) {

package/src/types.ts

@@ -1,6 +1,4 @@
-export type KichiForwarderConfig = {
-  defaultHost: string;
-};
+export type KichiForwarderConfig = Record<string, never>;
 
 export type PoseType = "stand" | "sit" | "lay" | "floor";
 
@@ -29,7 +27,7 @@ export type Album = {
 };
 
 export type KichiState = {
-  currentHost: string;
+  currentHost?: string;
   llmRuntimeEnabled: boolean;
 };
 
@@ -39,9 +37,10 @@ export type KichiIdentity = {
 };
 
 export type KichiConnectionStatus = {
-  host: string;
-  wsUrl: string;
-  identityPath: string;
+  host?: string;
+  wsUrl?: string;
+  identityPath?: string;
+  hostConfigured: boolean;
   connected: boolean;
   websocketState: "idle" | "connecting" | "open" | "closing" | "closed";
   hasIdentity: boolean;

package/.claude/settings.local.json

@@ -1,26 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "WebSearch",
-      "WebFetch(domain:raw.githubusercontent.com)",
-      "WebFetch(domain:github.com)",
-      "Bash(curl:*)",
-      "Bash(python -c:*)",
-      "Bash(chcp 65001:*)",
-      "Bash(set:*)",
-      "Bash(python -u -c:*)",
-      "Bash(gh api:*)",
-      "WebFetch(domain:docs.openclaw.ai)",
-      "WebFetch(domain:openclawskill.cc)",
-      "WebFetch(domain:yingtu.ai)",
-      "WebFetch(domain:lumadock.com)",
-      "WebFetch(domain:dev.to)",
-      "WebFetch(domain:www.learnclawdbot.org)",
-      "Bash(gh auth status:*)",
-      "WebFetch(domain:playbooks.com)",
-      "WebFetch(domain:smithery.ai)",
-      "WebFetch(domain:lobehub.com)",
-      "WebFetch(domain:snyk.io)"
-    ]
-  }
-}

package/.github/workflows/static.yml

@@ -1,43 +0,0 @@
-# Simple workflow for deploying static content to GitHub Pages
-name: Deploy static content to Pages
-
-on:
-  # Runs on pushes targeting the default branch
-  push:
-    branches: ["main"]
-
-  # Allows you to run this workflow manually from the Actions tab
-  workflow_dispatch:
-
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
-concurrency:
-  group: "pages"
-  cancel-in-progress: false
-
-jobs:
-  # Single deploy job since we're just deploying
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          # Upload entire repository
-          path: 'skills/kichi-forwarder'
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4