@yahaha-studio/kichi-forwarder 0.1.0-beta.9 → 0.1.1-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.1.0-beta.9",
+  "version": "0.1.1-beta.2",
   "description": "Native OpenClaw plugin for Kichi World with direct avatar control, status sync, timers, notes, and music tools",
   "type": "module",
   "main": "index.ts",

package/skills/kichi-forwarder/SKILL.md

@@ -23,10 +23,10 @@ If this skill is loaded from a remote URL before local installation, use these f
 
 ## Runtime State
 
-Runtime data lives under the user home directory:
+Runtime data lives under the user home directory and is isolated per OpenClaw agent:
 
-- `state.json`: stores `currentHost` and `llmRuntimeEnabled`
-- `hosts/<encoded-host>/identity.json`: stores host-specific `avatarId` and `authKey`
+- `kichi-world/agents/<encoded-agent-id>/state.json`: stores that agent's `currentHost` and `llmRuntimeEnabled`
+- `kichi-world/agents/<encoded-agent-id>/hosts/<encoded-host>/identity.json`: stores that agent's host-specific `avatarId` and `authKey`
 
 ## Remote URL Install Entry
 
@@ -53,7 +53,7 @@ For install/onboarding/connect requests:
 
 ## LLM Runtime
 
-`llmRuntimeEnabled` lives in `state.json`.
+`llmRuntimeEnabled` lives in the current agent's `state.json`.
 
 - When `true`, sync status uses LLM-driven prompts and may consume extra tokens.
 - When `false`, sync uses fixed English text.
@@ -172,8 +172,8 @@ kichi_music_album_create(albumTitle: "Deep Focus Mix", musicTitles: ["Calm Time"
 
 Plugin runtime directory:
 
-- Linux/macOS: `~/.openclaw/kichi-world/`
-- Windows: `%USERPROFILE%\.openclaw\kichi-world\`
+- Linux/macOS: `~/.openclaw/kichi-world/agents/<encoded-agent-id>/`
+- Windows: `%USERPROFILE%\.openclaw\kichi-world\agents\<encoded-agent-id>\`
 
 Runtime files:
 

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

@@ -6,10 +6,10 @@
 
 ## Runtime Files
 
-Persist runtime state to `state.json`:
+Persist runtime state to the current agent's `state.json`:
 
-- Linux/macOS: `~/.openclaw/kichi-world/state.json`
-- Windows: `%USERPROFILE%\.openclaw\kichi-world\state.json`
+- Linux/macOS: `~/.openclaw/kichi-world/agents/<encoded-agent-id>/state.json`
+- Windows: `%USERPROFILE%\.openclaw\kichi-world\agents\<encoded-agent-id>\state.json`
 
 ```json
 {
@@ -18,10 +18,10 @@ Persist runtime state to `state.json`:
 }
 ```
 
-Save `avatarId` to the host-specific `identity.json` before using `kichi_join`:
+Save `avatarId` to the current agent's host-specific `identity.json` before using `kichi_join`:
 
-- Linux/macOS: `~/.openclaw/kichi-world/hosts/<encoded-host>/identity.json`
-- Windows: `%USERPROFILE%\.openclaw\kichi-world\hosts\<encoded-host>\identity.json`
+- Linux/macOS: `~/.openclaw/kichi-world/agents/<encoded-agent-id>/hosts/<encoded-host>/identity.json`
+- Windows: `%USERPROFILE%\.openclaw\kichi-world\agents\<encoded-agent-id>\hosts\<encoded-host>\identity.json`
 
 ```json
 {
@@ -67,23 +67,27 @@ 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`.
-5. If step 4 fails with `429`, do not retry the same bare package command. Run `npm pack @yahaha-studio/kichi-forwarder`, then install the generated `.tgz` with `openclaw plugins install <tgz-path>`.
-6. Ensure the plugin is installed and enabled.
-7. If the plugin was newly installed or upgraded in this flow, re-check workspace `HEARTBEAT.md` against the latest Kichi heartbeat requirements before continuing.
-8. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Gate` from [heartbeat.md](heartbeat.md).
-9. If `HEARTBEAT.md` was not updated successfully, report setup as incomplete and stop immediately. Do not continue to `kichi_status` or `kichi_join`.
-10. Call `kichi_status`.
-11. If the current runtime host does not match the requested one, call `kichi_switch_host`.
-12. If `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
-13. Call `kichi_status` again and confirm connection and auth state.
+3. Resolve the host and write the current agent's `state.json`.
+4. Check whether `@yahaha-studio/kichi-forwarder` is already installed.
+5. If the plugin already exists, check whether the installed version is the latest published version.
+6. If the plugin is missing, run `openclaw plugins install @yahaha-studio/kichi-forwarder`.
+7. If the plugin is already installed but the version is not the latest, run `openclaw plugins update @yahaha-studio/kichi-forwarder`.
+8. If step 6 fails with `429`, do not retry the same bare package command. Run `npm pack @yahaha-studio/kichi-forwarder`, then install the generated `.tgz` with `openclaw plugins install <tgz-path>`.
+9. If step 7 fails with `429`, do not retry the same bare package command. Run `npm pack @yahaha-studio/kichi-forwarder`, then overwrite the existing install with `openclaw plugins install <tgz-path> --force`.
+10. Ensure the plugin is installed, enabled, and at the latest version.
+11. If the plugin was newly installed or upgraded in this flow, re-check workspace `HEARTBEAT.md` against the latest Kichi heartbeat requirements before continuing.
+12. Update workspace `HEARTBEAT.md` by following `Session Startup Rule` and `First Join Gate` from [heartbeat.md](heartbeat.md).
+13. If `HEARTBEAT.md` was not updated successfully, report setup as incomplete and stop immediately. Do not continue to `kichi_status` or `kichi_join`.
+14. Call `kichi_status`.
+15. If the current agent runtime host does not match the requested one, call `kichi_switch_host`.
+16. If `authKey` is missing, call `kichi_join` with parsed `avatarId`, `botName`, `bio`, and `tags`.
+17. Call `kichi_status` again and confirm connection and auth state.
 
 ## Required Post-install Integration
 
 Use this completion checklist:
 
-- [ ] plugin installed and enabled
+- [ ] plugin installed, enabled, and at latest version
 - [ ] `HEARTBEAT.md` updated with the Kichi heartbeat workflow snippet from [heartbeat.md](heartbeat.md)
 - [ ] `kichi_status` verified the final connected/auth state
 

package/src/runtime-manager.ts

@@ -0,0 +1,240 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { Logger } from "openclaw/plugin-sdk";
+import { KichiForwarderService } from "./service.js";
+
+const OPENCLAW_HOME_DIR = path.join(os.homedir(), ".openclaw");
+const KICHI_WORLD_ROOT_DIR = path.join(OPENCLAW_HOME_DIR, "kichi-world");
+const CANONICAL_AGENT_ROOT_DIR = path.join(KICHI_WORLD_ROOT_DIR, "agents");
+const PREVIOUS_AGENT_ROOT_DIR = path.join(OPENCLAW_HOME_DIR, "kichi-forwarder", "agents");
+const LEGACY_GLOBAL_STATE_PATH = path.join(KICHI_WORLD_ROOT_DIR, "state.json");
+const LEGACY_GLOBAL_HOSTS_DIR = path.join(KICHI_WORLD_ROOT_DIR, "hosts");
+const LEGACY_MIGRATION_AGENT_ID = "main";
+
+type AgentLocator = {
+  agentId?: string;
+  ctxAgentId?: string;
+  sessionKey?: string;
+};
+
+export class KichiRuntimeManager {
+  private services = new Map<string, KichiForwarderService>();
+
+  constructor(private logger: Logger) {}
+
+  getRuntime(locator: AgentLocator): KichiForwarderService | null {
+    const agentId = this.resolveAgentId(locator);
+    if (!agentId) {
+      return null;
+    }
+
+    return this.services.get(agentId) ?? null;
+  }
+
+  resolveRuntimeAgentId(locator: AgentLocator): string | null {
+    return this.resolveAgentId(locator);
+  }
+
+  createRuntimeForAgent(agentId: string): KichiForwarderService {
+    const normalizedAgentId = this.normalizeAgentId(agentId);
+    if (!normalizedAgentId) {
+      throw new Error("Cannot create Kichi runtime without a valid agentId");
+    }
+
+    const existing = this.services.get(normalizedAgentId);
+    if (existing) {
+      return existing;
+    }
+
+    return this.createRuntime(normalizedAgentId);
+  }
+
+  initializeStartupRuntimes(): void {
+    this.migrateRuntimeStorage();
+
+    const rootDir = CANONICAL_AGENT_ROOT_DIR;
+    if (!fs.existsSync(rootDir)) {
+      return;
+    }
+
+    for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      const runtimeDir = path.join(rootDir, entry.name);
+      const statePath = path.join(runtimeDir, "state.json");
+      if (!fs.existsSync(statePath)) {
+        continue;
+      }
+
+      const agentId = decodeURIComponent(entry.name);
+      if (this.services.has(agentId)) {
+        continue;
+      }
+
+      this.createRuntime(agentId);
+    }
+  }
+
+  stopAll(): void {
+    for (const service of this.services.values()) {
+      service.stop();
+    }
+    this.services.clear();
+  }
+
+  private resolveAgentId(locator: AgentLocator): string | null {
+    const directAgentId = this.normalizeAgentId(locator.ctxAgentId) ?? this.normalizeAgentId(locator.agentId);
+    const sessionAgentId =
+      typeof locator.sessionKey === "string" && locator.sessionKey.trim()
+        ? this.parseAgentIdFromSessionKey(locator.sessionKey)
+        : null;
+
+    if (sessionAgentId) {
+      if (directAgentId && directAgentId !== sessionAgentId) {
+        this.logger.error(
+          `[kichi] runtime scope mismatch: directAgentId=${directAgentId} sessionAgentId=${sessionAgentId} sessionKey=${locator.sessionKey}`,
+        );
+      }
+      this.logger.debug(`[kichi] resolved agent runtime from sessionKey: ${sessionAgentId}`);
+      return sessionAgentId;
+    }
+
+    return directAgentId;
+  }
+
+  private normalizeAgentId(value: unknown): string | null {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+  }
+
+  private parseAgentIdFromSessionKey(sessionKey: string): string | null {
+    const trimmed = sessionKey.trim();
+    const match = /^agent:([^:]+):/i.exec(trimmed);
+    if (!match) {
+      return null;
+    }
+    return this.normalizeAgentId(match[1]);
+  }
+
+  private migrateRuntimeStorage(): void {
+    // Temporary startup migration for this release. Remove after users have
+    // moved off the legacy/global layout and the temporary kichi-forwarder path.
+    this.runMigrationStep("previous-agent-root", () => {
+      this.migratePreviousAgentRoot();
+    });
+    this.runMigrationStep("legacy-global-root", () => {
+      this.migrateLegacyGlobalRoot();
+    });
+  }
+
+  private migratePreviousAgentRoot(): void {
+    if (!fs.existsSync(PREVIOUS_AGENT_ROOT_DIR)) {
+      return;
+    }
+
+    if (!fs.existsSync(CANONICAL_AGENT_ROOT_DIR)) {
+      fs.mkdirSync(path.dirname(CANONICAL_AGENT_ROOT_DIR), { recursive: true, mode: 0o700 });
+      fs.renameSync(PREVIOUS_AGENT_ROOT_DIR, CANONICAL_AGENT_ROOT_DIR);
+      this.logger.info(`[kichi:migration] moved ${PREVIOUS_AGENT_ROOT_DIR} to ${CANONICAL_AGENT_ROOT_DIR}`);
+      return;
+    }
+
+    for (const entry of fs.readdirSync(PREVIOUS_AGENT_ROOT_DIR, { withFileTypes: true })) {
+      const sourcePath = path.join(PREVIOUS_AGENT_ROOT_DIR, entry.name);
+      const targetPath = path.join(CANONICAL_AGENT_ROOT_DIR, entry.name);
+      this.movePathIntoTarget(sourcePath, targetPath);
+    }
+    this.removeDirectoryIfEmpty(PREVIOUS_AGENT_ROOT_DIR);
+    this.removeDirectoryIfEmpty(path.dirname(PREVIOUS_AGENT_ROOT_DIR));
+  }
+
+  private migrateLegacyGlobalRoot(): void {
+    const hasLegacyState = fs.existsSync(LEGACY_GLOBAL_STATE_PATH);
+    const hasLegacyHosts = fs.existsSync(LEGACY_GLOBAL_HOSTS_DIR);
+    if (!hasLegacyState && !hasLegacyHosts) {
+      return;
+    }
+
+    const targetRuntimeDir = this.getRuntimeDir(LEGACY_MIGRATION_AGENT_ID);
+    fs.mkdirSync(targetRuntimeDir, { recursive: true, mode: 0o700 });
+
+    if (hasLegacyState) {
+      const targetStatePath = path.join(targetRuntimeDir, "state.json");
+      this.movePathIntoTarget(LEGACY_GLOBAL_STATE_PATH, targetStatePath);
+    }
+
+    if (hasLegacyHosts) {
+      const targetHostsDir = path.join(targetRuntimeDir, "hosts");
+      this.movePathIntoTarget(LEGACY_GLOBAL_HOSTS_DIR, targetHostsDir);
+    }
+  }
+
+  private movePathIntoTarget(sourcePath: string, targetPath: string): void {
+    if (!fs.existsSync(sourcePath)) {
+      return;
+    }
+
+    if (!fs.existsSync(targetPath)) {
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true, mode: 0o700 });
+      fs.renameSync(sourcePath, targetPath);
+      this.logger.info(`[kichi:migration] moved ${sourcePath} to ${targetPath}`);
+      return;
+    }
+
+    const sourceStat = fs.lstatSync(sourcePath);
+    const targetStat = fs.lstatSync(targetPath);
+
+    if (sourceStat.isDirectory() && targetStat.isDirectory()) {
+      for (const entry of fs.readdirSync(sourcePath, { withFileTypes: true })) {
+        const nextSourcePath = path.join(sourcePath, entry.name);
+        const nextTargetPath = path.join(targetPath, entry.name);
+        this.movePathIntoTarget(nextSourcePath, nextTargetPath);
+      }
+      this.removeDirectoryIfEmpty(sourcePath);
+      return;
+    }
+
+    fs.rmSync(sourcePath, { recursive: sourceStat.isDirectory(), force: true });
+    this.logger.warn(`[kichi:migration] dropped ${sourcePath} because target already exists at ${targetPath}`);
+  }
+
+  private removeDirectoryIfEmpty(dirPath: string): void {
+    if (!fs.existsSync(dirPath)) {
+      return;
+    }
+    if (!fs.lstatSync(dirPath).isDirectory()) {
+      return;
+    }
+    if (fs.readdirSync(dirPath).length > 0) {
+      return;
+    }
+    fs.rmdirSync(dirPath);
+  }
+
+  private runMigrationStep(label: string, fn: () => void): void {
+    try {
+      fn();
+    } catch (error) {
+      this.logger.warn(`[kichi:migration] skipped ${label} due to error: ${String(error)}`);
+    }
+  }
+
+  private createRuntime(agentId: string): KichiForwarderService {
+    const runtimeDir = this.getRuntimeDir(agentId);
+    fs.mkdirSync(runtimeDir, { recursive: true, mode: 0o700 });
+
+    const service = new KichiForwarderService(this.logger, {
+      agentId,
+      runtimeDir,
+    });
+    service.start();
+    this.services.set(agentId, service);
+    this.logger.debug(`[kichi:${agentId}] runtime initialized at ${runtimeDir}`);
+    return service;
+  }
+
+  private getRuntimeDir(agentId: string): string {
+    return path.join(CANONICAL_AGENT_ROOT_DIR, encodeURIComponent(agentId));
+  }
+}