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

package/README.md

@@ -50,15 +50,15 @@ Get the `host` and `avatarId` from Kichi, then use them with `kichi_switch_host`
 
 ## Runtime State
 
-The plugin stores runtime state in the OpenClaw user directory:
+The plugin stores runtime state per OpenClaw agent in the OpenClaw user directory:
 
-- Windows: `%USERPROFILE%\.openclaw\kichi-world\`
-- Linux/macOS: `~/.openclaw/kichi-world/`
+- Windows: `%USERPROFILE%\.openclaw\kichi-world\agents\<encoded-agent-id>\`
+- Linux/macOS: `~/.openclaw/kichi-world/agents/<encoded-agent-id>/`
 
-Important files:
+Important files for each agent:
 
-- `state.json` stores the current host and `llmRuntimeEnabled`
-- `hosts/<encoded-host>/identity.json` stores host-specific `avatarId` and `authKey`
+- `state.json` stores that agent's current host and `llmRuntimeEnabled`
+- `hosts/<encoded-host>/identity.json` stores that agent's host-specific `avatarId` and `authKey`
 
 ## Notes
 

package/index.ts

@@ -1,9 +1,12 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
+import fs from "node:fs";
 import { fileURLToPath } from "node:url";
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type {
+  AnyAgentTool,
+  OpenClawPluginApi,
+  OpenClawPluginToolContext,
+} from "openclaw/plugin-sdk";
 import { parse } from "./src/config.js";
+import { KichiRuntimeManager } from "./src/runtime-manager.js";
 import { KichiForwarderService } from "./src/service.js";
 import type {
   ActionDefinition,
@@ -12,13 +15,11 @@ import type {
   Album,
   ClockAction,
   ClockConfig,
-  KichiState,
   KichiStaticConfig,
   PomodoroPhase,
   PoseType,
 } from "./src/types.js";
 const BUNDLED_STATIC_CONFIG_PATH = new URL("./config/kichi-config.json", import.meta.url);
-const DEFAULT_LLM_RUNTIME_ENABLED = true;
 const FIXED_HOOK_STATUSES: Record<string, ActionResult> = {
   beforePromptBuild: {
     poseType: "sit",
@@ -46,8 +47,6 @@ const FIXED_HOOK_STATUSES: Record<string, ActionResult> = {
   },
 };
 
-const KICHI_WORLD_DIR = path.join(os.homedir(), ".openclaw", "kichi-world");
-const STATE_PATH = path.join(KICHI_WORLD_DIR, "state.json");
 const MAX_NOTEBOARD_TEXT_LENGTH = 200;
 const MAX_MESSAGE_RECEIVED_PREVIEW_WIDTH = 20;
 const MAX_AGENT_END_PREVIEW_WIDTH = 10;
@@ -55,8 +54,6 @@ const MESSAGE_RECEIVED_ELLIPSIS = "...";
 const IDLE_PLAN_POMODORO_PHASES = ["focus", "shortBreak", "longBreak", "none"] as const;
 let cachedStaticConfig: KichiStaticConfig | null = null;
 let cachedStaticConfigMtime = 0;
-let service: KichiForwarderService | null = null;
-let pluginApi: OpenClawPluginApi | null = null;
 
 type IdlePlanPomodoroPhase = typeof IDLE_PLAN_POMODORO_PHASES[number];
 type IdlePlanAction = {
@@ -192,25 +189,6 @@ function normalizeStaticConfig(value: unknown): KichiStaticConfig {
   };
 }
 
-function readState(): KichiState {
-  if (!fs.existsSync(STATE_PATH)) {
-    return {
-      llmRuntimeEnabled: DEFAULT_LLM_RUNTIME_ENABLED,
-    };
-  }
-  const data = JSON.parse(fs.readFileSync(STATE_PATH, "utf-8")) as Partial<KichiState>;
-  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 {
-    ...(typeof data.currentHost === "string" ? { currentHost: data.currentHost } : {}),
-    llmRuntimeEnabled: data.llmRuntimeEnabled,
-  };
-}
-
 function loadStaticConfig(): KichiStaticConfig {
   const configPath = fileURLToPath(BUNDLED_STATIC_CONFIG_PATH);
   const stat = fs.statSync(configPath);
@@ -222,9 +200,9 @@ function loadStaticConfig(): KichiStaticConfig {
   return cachedStaticConfig;
 }
 
-function sendStatusUpdate(status: ActionResult): void {
+function sendStatusUpdate(service: KichiForwarderService, status: ActionResult): void {
   const actionDefinition = getActionDefinition(status.poseType, status.action);
-  service?.sendStatus(
+  service.sendStatus(
     status.poseType,
     actionDefinition.name,
     status.bubble || status.action,
@@ -233,19 +211,15 @@ function sendStatusUpdate(status: ActionResult): void {
   );
 }
 
-function isLlmRuntimeEnabled(): boolean {
-  return readState().llmRuntimeEnabled;
-}
-
-function syncFixedStatus(status: ActionResult): void {
-  if (!service?.hasValidIdentity() || !service?.isConnected()) {
+function syncFixedStatus(service: KichiForwarderService, status: ActionResult): void {
+  if (!service.hasValidIdentity() || !service.isConnected()) {
     return;
   }
   const bubbleText = status.bubble.trim() || status.action;
   const logText = typeof status.log === "string" && status.log.trim()
     ? status.log.trim()
     : bubbleText;
-  sendStatusUpdate({
+  sendStatusUpdate(service, {
     ...status,
     bubble: bubbleText,
     log: logText,
@@ -304,6 +278,56 @@ function stripReplyTag(text: string): string {
   return text.replace(/^\[\[\s*reply_to(?::[^\]]+|_current)?\s*\]\]\s*/i, "").trim();
 }
 
+function stripKnownLeadingIdentifiers(text: string, candidates: string[]): string {
+  let normalized = text.trim();
+  if (!normalized) {
+    return "";
+  }
+
+  const separatorsPattern = String.raw`(?:[\s,:;，：；]|$)+`;
+  let changed = true;
+  while (changed && normalized) {
+    changed = false;
+    for (const candidate of candidates) {
+      const trimmed = candidate.trim();
+      if (!trimmed) {
+        continue;
+      }
+      const escaped = trimmed.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const patterns = [
+        new RegExp(`^${escaped}${separatorsPattern}`, "i"),
+        new RegExp(`^@${escaped}${separatorsPattern}`, "i"),
+        new RegExp(`^<@${escaped}>${separatorsPattern}`, "i"),
+      ];
+      for (const pattern of patterns) {
+        if (!pattern.test(normalized)) {
+          continue;
+        }
+        normalized = normalized.replace(pattern, "").trimStart();
+        changed = true;
+      }
+    }
+  }
+
+  return normalized.trim();
+}
+
+function stripDispatchMetadata(
+  text: string,
+  context?: {
+    senderId?: string;
+    accountId?: string;
+  },
+): string {
+  let normalized = stripReplyTag(text);
+  normalized = normalized.replace(/^(?:\[[a-z_]+:\s*[^\]]+\]\s*)+/i, "").trim();
+  normalized = stripKnownLeadingIdentifiers(normalized, [
+    typeof context?.senderId === "string" ? context.senderId : "",
+    typeof context?.accountId === "string" ? context.accountId : "",
+  ]);
+  return normalized;
+}
+
 function extractTextFromContent(content: unknown): string {
   if (typeof content === "string") {
     return stripReplyTag(content);
@@ -354,26 +378,62 @@ function getLastAssistantPreview(messages: unknown, maxWidth: number): string {
   return "";
 }
 
-async function handleMessageReceivedHook(content: string): Promise<void> {
-  const connected = service?.isConnected() ?? false;
-  const hasIdentity = service?.hasValidIdentity() ?? false;
-  pluginApi?.logger.info(`[kichi] message_received hook fired (connected=${connected}, hasIdentity=${hasIdentity})`);
+function resolveDispatchMessageText(
+  event: { body?: string; content: string },
+  context?: {
+    senderId?: string;
+    accountId?: string;
+  },
+): string {
+  if (typeof event.content === "string" && event.content.trim()) {
+    return stripDispatchMetadata(event.content, context);
+  }
+  if (typeof event.body === "string" && event.body.trim()) {
+    return stripDispatchMetadata(event.body, context);
+  }
+  return "";
+}
+
+function notifyMessageReceived(
+  api: OpenClawPluginApi,
+  service: KichiForwarderService,
+  content: string,
+): void {
+  const connected = service.isConnected();
+  const hasIdentity = service.hasValidIdentity();
+  api.logger.debug(`[kichi:${service.getAgentId()}] inbound sync fired (connected=${connected}, hasIdentity=${hasIdentity})`);
   if (!hasIdentity || !connected) {
-    pluginApi?.logger.warn("[kichi] skipped message_received notify because service is not ready");
+    api.logger.debug(`[kichi:${service.getAgentId()}] skipped inbound sync because runtime is not ready`);
     return;
   }
   const trimmed = truncateByDisplayWidth(content, MAX_MESSAGE_RECEIVED_PREVIEW_WIDTH);
-  pluginApi?.logger.info(`[kichi] sending message_received notify with preview: ${trimmed || "(empty)"}`);
+  api.logger.debug(`[kichi:${service.getAgentId()}] sending message_received notify with preview: ${trimmed || "(empty)"}`);
   service.sendHookNotify("message_received", `"${trimmed}"`);
 }
 
-function registerPluginHooks(api: OpenClawPluginApi): void {
+function registerPluginHooks(api: OpenClawPluginApi, runtimeManager: KichiRuntimeManager): void {
+  api.on("before_dispatch", (event, ctx) => {
+    const service = runtimeManager.getRuntime(ctx);
+    if (!service) {
+      return;
+    }
+    const content = resolveDispatchMessageText(event, {
+      senderId: ctx.senderId,
+      accountId: ctx.accountId,
+    });
+    if (!content) {
+      return;
+    }
+    notifyMessageReceived(api, service, content);
+  });
+
   api.on("before_prompt_build", (_event, ctx) => {
-    if (!service?.hasValidIdentity() || !service?.isConnected()) {
+    const service = runtimeManager.getRuntime(ctx);
+    if (!service?.hasValidIdentity() || !service.isConnected()) {
       return;
     }
-    if (!isLlmRuntimeEnabled()) {
-      syncFixedStatus(FIXED_HOOK_STATUSES.beforePromptBuild);
+    if (!service.isLlmRuntimeEnabled()) {
+      syncFixedStatus(service, FIXED_HOOK_STATUSES.beforePromptBuild);
       return;
     }
     if (ctx.trigger === "heartbeat") {
@@ -384,32 +444,36 @@ function registerPluginHooks(api: OpenClawPluginApi): void {
     };
   });
 
-  api.on("before_tool_call", (_event, _ctx) => {
-    if (!isLlmRuntimeEnabled()) {
-      syncFixedStatus(FIXED_HOOK_STATUSES.beforeToolCall);
+  api.on("before_tool_call", (_event, ctx) => {
+    const service = runtimeManager.getRuntime(ctx);
+    if (!service) {
+      return;
+    }
+    if (!service.isLlmRuntimeEnabled()) {
+      syncFixedStatus(service, FIXED_HOOK_STATUSES.beforeToolCall);
     }
-  });
-
-  api.on("message_received", async (event) => {
-    await handleMessageReceivedHook(event.content);
   });
 
   api.on("agent_end", (event, ctx) => {
+    const service = runtimeManager.getRuntime(ctx);
     const preview = getLastAssistantPreview(event.messages, MAX_AGENT_END_PREVIEW_WIDTH);
-    pluginApi?.logger.info(
-      `[kichi] agent_end hook fired (trigger=${ctx.trigger ?? "unknown"}, success=${event.success}, durationMs=${event.durationMs ?? 0}, error=${event.error ?? ""}, preview=${preview || "(empty)"})`,
+    api.logger.debug(
+      `[kichi:${service?.getAgentId() ?? "unknown"}] agent_end fired (trigger=${ctx.trigger ?? "unknown"}, success=${event.success}, durationMs=${event.durationMs ?? 0}, error=${event.error ?? ""}, preview=${preview || "(empty)"})`,
     );
     if (ctx.trigger === "heartbeat") {
       return;
     }
-    if (event.success && preview) {
-      pluginApi?.logger.info(`[kichi] sending before_send_message notify from agent_end with bubble: ${preview}`);
-      service?.sendHookNotify("before_send_message", preview);
+    if (service && event.success && preview) {
+      api.logger.debug(`[kichi:${service.getAgentId()}] sending before_send_message notify with bubble: ${preview}`);
+      service.sendHookNotify("before_send_message", preview);
     }
-    if (isLlmRuntimeEnabled()) {
+    if (!service || service.isLlmRuntimeEnabled()) {
       return;
     }
-    syncFixedStatus(event.success ? FIXED_HOOK_STATUSES.agentEndSuccess : FIXED_HOOK_STATUSES.agentEndFailure);
+    syncFixedStatus(
+      service,
+      event.success ? FIXED_HOOK_STATUSES.agentEndSuccess : FIXED_HOOK_STATUSES.agentEndFailure,
+    );
   });
 }
 function isPlainObject(value: unknown): value is Record<string, unknown> {
@@ -875,27 +939,41 @@ function buildKichiPrompt(): string {
   ].join("\n");
 }
 
+function createAgentScopedTool(
+  runtimeManager: KichiRuntimeManager,
+  factory: (service: KichiForwarderService, ctx: OpenClawPluginToolContext) => AnyAgentTool,
+) {
+  return (ctx: OpenClawPluginToolContext) => {
+    const service = runtimeManager.getRuntime(ctx, { createIfMissing: true });
+    if (!service) {
+      throw new Error("Failed to resolve agent-scoped Kichi runtime");
+    }
+    return factory(service, ctx);
+  };
+}
+
 const plugin = {
   id: "kichi-forwarder",
   name: "Kichi Forwarder",
   configSchema: { parse },
 
   register(api: OpenClawPluginApi) {
-    pluginApi = api;
-    registerPluginHooks(api);
+    const runtimeManager = new KichiRuntimeManager(api.logger);
+    registerPluginHooks(api, runtimeManager);
     const musicTitleEnum = getMusicTitleEnum();
 
     api.registerService({
       id: "kichi-forwarder",
       start: (ctx) => {
         parse(ctx.config.plugins?.entries?.["kichi-forwarder"]?.config);
-        service = new KichiForwarderService(api.logger);
-        return service.start();
+        runtimeManager.startPersistedRuntimes();
+      },
+      stop: () => {
+        runtimeManager.stopAll();
       },
-      stop: () => service?.stop(),
     });
 
-    api.registerTool({
+    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_join",
       description: "Join Kichi world with avatarId, the current bot name, a short bio, and personality tags",
       parameters: {
@@ -926,7 +1004,7 @@ const plugin = {
           (params as { tags?: unknown } | null)?.tags,
         );
         if (!avatarId) {
-          avatarId = service?.readSavedAvatarId() ?? undefined;
+          avatarId = service.readSavedAvatarId() ?? undefined;
         }
         if (!avatarId) {
           return { success: false, error: "No avatarId" };
@@ -940,10 +1018,7 @@ const plugin = {
         if (tagsError) {
           return { success: false, error: tagsError };
         }
-        const result = await service?.join(avatarId, botName, bio, tags ?? []);
-        if (!result) {
-          return { success: false, error: "Kichi service is not initialized" };
-        }
+        const result = await service.join(avatarId, botName, bio, tags ?? []);
         if (result.success) {
           return { success: true, authKey: result.authKey };
         }
@@ -954,9 +1029,9 @@ const plugin = {
           ...(result.errorMessage ? { errorMessage: result.errorMessage } : {}),
         };
       },
-    });
+    })));
 
-    api.registerTool({
+    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_switch_host",
       description:
         "Switch Kichi runtime host and reconnect immediately without restarting the gateway.",
@@ -971,9 +1046,6 @@ const plugin = {
         required: ["host"],
       },
       execute: async (_toolCallId, params) => {
-        if (!service) {
-          return { success: false, error: "Kichi service is not initialized" };
-        }
         const host = (params as { host?: unknown } | null)?.host;
         if (!isKichiHost(host)) {
           return { success: false, error: "host must be a non-empty hostname without protocol or path" };
@@ -986,18 +1058,14 @@ const plugin = {
           status,
         };
       },
-    });
+    })));
 
-    api.registerTool({
+    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_rejoin",
       description:
         "Request an immediate rejoin attempt with saved avatarId/authKey. Rejoin is also sent automatically after reconnect.",
       parameters: { type: "object", properties: {} },
       execute: async () => {
-        if (!service) {
-          return { success: false, error: "Kichi service is not initialized" };
-        }
-
         const result = service.requestRejoin();
         return {
           success: result.accepted,
@@ -1005,17 +1073,14 @@ const plugin = {
           status: service.getConnectionStatus(),
         };
       },
-    });
+    })));
 
-    api.registerTool({
+    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_leave",
       description: "Leave Kichi world",
       parameters: { type: "object", properties: {} },
       execute: async () => {
-        const result = await service?.leave();
-        if (!result) {
-          return { success: false, error: "Kichi service is not initialized" };
-        }
+        const result = await service.leave();
         if (result.success) {
           return { success: true };
         }
@@ -1026,24 +1091,21 @@ const plugin = {
           ...(result.errorMessage ? { errorMessage: result.errorMessage } : {}),
         };
       },
-    });
+    })));
 
-    api.registerTool({
+    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_status",
       description: "Read current Kichi connection status and identity readiness",
       parameters: { type: "object", properties: {} },
       execute: async () => {
-        if (!service) {
-          return { success: false, error: "Kichi service is not initialized" };
-        }
         return {
           success: true,
           status: service.getConnectionStatus(),
         };
       },
-    });
+    })));
 
-    api.registerTool({
+    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_action",
       description: buildKichiActionDescription(),
       parameters: {
@@ -1079,7 +1141,7 @@ const plugin = {
             error: `Invalid poseType: ${poseType}. Must be stand, sit, lay, or floor`,
           };
         }
-        if (!service?.hasValidIdentity() || !service?.isConnected()) {
+        if (!service.hasValidIdentity() || !service.isConnected()) {
           return { success: false, error: "Not connected to Kichi world" };
         }
 
@@ -1097,6 +1159,7 @@ const plugin = {
         const bubbleText = typeof bubble === "string" && bubble.trim() ? bubble.trim() : matched.name;
         const logText = typeof log === "string" ? log.trim() : "";
         sendStatusUpdate(
+          service,
           {
             poseType: normalizedPoseType,
             action: matched.name,
@@ -1113,8 +1176,8 @@ const plugin = {
           playback: getActionPlayback(matched),
         };
       },
-    });
-    api.registerTool({
+    })));
+    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_idle_plan",
       description: buildKichiIdlePlanDescription(),
       parameters: {
@@ -1197,7 +1260,7 @@ const plugin = {
         if (!idlePlan) {
           return { success: false, error: error ?? "Invalid idle plan payload" };
         }
-        if (!service?.hasValidIdentity() || !service?.isConnected()) {
+        if (!service.hasValidIdentity() || !service.isConnected()) {
           return { success: false, error: "Not connected to Kichi world" };
         }
         const sent = service.sendIdlePlan({
@@ -1218,8 +1281,8 @@ const plugin = {
           stages: idlePlan.stages,
         };
       },
-    });
-    api.registerTool({
+    })));
+    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_clock",
       description:
         "Send clock commands to Kichi world. Supported actions are set and stop.",
@@ -1304,7 +1367,7 @@ const plugin = {
           return { success: false, error: "requestId must be a string when provided" };
         }
         const normalizedRequestId = typeof requestId === "string" ? requestId : undefined;
-        if (!service?.hasValidIdentity() || !service?.isConnected()) {
+        if (!service.hasValidIdentity() || !service.isConnected()) {
           return { success: false, error: "Not connected to Kichi world" };
         }
 
@@ -1329,9 +1392,9 @@ const plugin = {
           ...(normalizedClock ? { clock: normalizedClock } : {}),
         };
       },
-    });
+    })));
 
-    api.registerTool({
+    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_query_status",
       description:
         "Query Kichi avatar status (notes, ownerState, idlePlan, weather/time, timer snapshot, daily note quota, and `hasCreatedMusicAlbumToday`). 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.",
@@ -1349,7 +1412,7 @@ const plugin = {
         if (requestId !== undefined && typeof requestId !== "string") {
           return { success: false, error: "requestId must be a string when provided" };
         }
-        if (!service?.hasValidIdentity() || !service?.isConnected()) {
+        if (!service.hasValidIdentity() || !service.isConnected()) {
           return { success: false, error: "Not connected to Kichi world" };
         }
 
@@ -1365,9 +1428,9 @@ const plugin = {
           };
         }
       },
-    });
+    })));
 
-    api.registerTool({
+    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_music_album_create",
       description: buildMusicAlbumToolDescription(),
       parameters: {
@@ -1429,7 +1492,7 @@ const plugin = {
             examples: getMusicTitleExamples(),
           };
         }
-        if (!service?.hasValidIdentity() || !service?.isConnected()) {
+        if (!service.hasValidIdentity() || !service.isConnected()) {
           return { success: false, error: "Not connected to Kichi world" };
         }
 
@@ -1453,9 +1516,9 @@ const plugin = {
           };
         }
       },
-    });
+    })));
 
-    api.registerTool({
+    api.registerTool(createAgentScopedTool(runtimeManager, (service) => ({
       name: "kichi_noteboard_create",
       description:
         "Create a new note on a specific Kichi note board. Prefer querying first so you can avoid duplicate posts and respect rate limits.",
@@ -1490,7 +1553,7 @@ const plugin = {
             error: `data must be ${MAX_NOTEBOARD_TEXT_LENGTH} characters or fewer`,
           };
         }
-        if (!service?.hasValidIdentity() || !service?.isConnected()) {
+        if (!service.hasValidIdentity() || !service.isConnected()) {
           return { success: false, error: "Not connected to Kichi world" };
         }
 
@@ -1504,7 +1567,7 @@ const 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.0-beta.9",
+  "version": "0.1.1-beta.1",
   "author": "OpenClaw",
   "skills": ["./skills/kichi-forwarder"],
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yahaha-studio/kichi-forwarder",
-  "version": "0.1.0-beta.9",
+  "version": "0.1.1-beta.1",
   "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,223 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { Logger } from "openclaw/plugin-sdk";
+import { resolveAgentIdFromSessionKey } from "openclaw/plugin-sdk/routing";
+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;
+  sessionKey?: string;
+};
+
+type GetRuntimeOptions = {
+  createIfMissing?: boolean;
+};
+
+export class KichiRuntimeManager {
+  private services = new Map<string, KichiForwarderService>();
+
+  constructor(private logger: Logger) {}
+
+  getRuntime(locator: AgentLocator, options: GetRuntimeOptions = {}): KichiForwarderService | null {
+    const agentId = this.resolveAgentId(locator);
+    if (!agentId) {
+      return null;
+    }
+
+    const existing = this.services.get(agentId);
+    if (existing) {
+      return existing;
+    }
+
+    if (!options.createIfMissing && !this.hasPersistedRuntime(agentId)) {
+      return null;
+    }
+
+    return this.createRuntime(agentId);
+  }
+
+  startPersistedRuntimes(): 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 {
+    if (typeof locator.agentId === "string" && locator.agentId.trim()) {
+      return locator.agentId.trim();
+    }
+
+    if (typeof locator.sessionKey !== "string" || !locator.sessionKey.trim()) {
+      return null;
+    }
+
+    try {
+      const agentId = resolveAgentIdFromSessionKey(locator.sessionKey);
+      return typeof agentId === "string" && agentId.trim() ? agentId.trim() : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private hasPersistedRuntime(agentId: string): boolean {
+    return fs.existsSync(path.join(this.getRuntimeDir(agentId), "state.json"));
+  }
+
+  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));
+  }
+}

package/src/service.ts

@@ -1,6 +1,5 @@
 import WebSocket from "ws";
 import * as fs from "fs";
-import os from "node:os";
 import * as path from "path";
 import { randomUUID } from "node:crypto";
 import type { Logger } from "openclaw/plugin-sdk";
@@ -27,9 +26,6 @@ import type {
   StatusPayload,
 } from "./types.js";
 
-const KICHI_WORLD_DIR = path.join(os.homedir(), ".openclaw", "kichi-world");
-const HOSTS_DIR = path.join(KICHI_WORLD_DIR, "hosts");
-const STATE_PATH = path.join(KICHI_WORLD_DIR, "state.json");
 const MAX_NOTEBOARD_TEXT_LENGTH = 200;
 const DEFAULT_LLM_RUNTIME_ENABLED = true;
 
@@ -53,6 +49,11 @@ export type LeaveResult =
     }
   | AckFailureResult;
 
+type KichiForwarderServiceOptions = {
+  agentId: string;
+  runtimeDir: string;
+};
+
 export class KichiForwarderService {
   private ws: WebSocket | null = null;
   private stopped = false;
@@ -70,9 +71,12 @@ export class KichiForwarderService {
     }
   >();
 
-  constructor(private logger: Logger) {}
+  constructor(
+    private logger: Logger,
+    private options: KichiForwarderServiceOptions,
+  ) {}
 
-  async start(): Promise<void> {
+  start(): void {
     this.host = this.loadCurrentHost();
     this.identity = this.host ? this.loadIdentity() : null;
     this.stopped = false;
@@ -80,10 +84,10 @@ export class KichiForwarderService {
       this.connect();
       return;
     }
-    this.logger.info("Kichi host is not configured yet; waiting for kichi_switch_host");
+    this.log("debug", "host is not configured yet; waiting for kichi_switch_host");
   }
 
-  async stop(): Promise<void> {
+  stop(): void {
     this.stopped = true;
     this.clearReconnectTimeout();
     this.rejectPendingRequests("Kichi websocket stopped");
@@ -270,10 +274,26 @@ export class KichiForwarderService {
 
   hasValidIdentity(): boolean { return !!this.identity?.avatarId && !!this.identity?.authKey; }
 
+  isLlmRuntimeEnabled(): boolean {
+    return this.readStateFile()?.llmRuntimeEnabled ?? DEFAULT_LLM_RUNTIME_ENABLED;
+  }
+
   getCurrentHost(): string {
     return this.host ?? "";
   }
 
+  getAgentId(): string {
+    return this.options.agentId;
+  }
+
+  getRuntimeDir(): string {
+    return this.options.runtimeDir;
+  }
+
+  getStatePath(): string {
+    return path.join(this.options.runtimeDir, "state.json");
+  }
+
   getIdentityPath(): string {
     if (!this.host) {
       return "";
@@ -336,6 +356,9 @@ export class KichiForwarderService {
   getConnectionStatus(): KichiConnectionStatus {
     const host = this.host ?? undefined;
     return {
+      agentId: this.options.agentId,
+      runtimeDir: this.getRuntimeDir(),
+      statePath: this.getStatePath(),
       ...(host ? {
         host,
         wsUrl: this.getWsUrl(),
@@ -372,7 +395,7 @@ export class KichiForwarderService {
             resolve({ success: true });
           }
         } catch (e) {
-          this.logger.warn(`Failed to parse leave response: ${e}`);
+          this.log("warn", `failed to parse leave response: ${e}`);
         }
       };
       this.ws!.on("message", handler);
@@ -395,7 +418,7 @@ export class KichiForwarderService {
 
     ws.on("open", () => {
       if (this.ws !== ws) return;
-      this.logger.info(`Connected to ${wsUrl} (${this.host})`);
+      this.log("info", `connected to ${wsUrl} (${this.host})`);
       this.sendRejoinPayload();
     });
 
@@ -420,7 +443,7 @@ export class KichiForwarderService {
   }
 
   private handleMessage(data: string): void {
-    this.logger.debug(`[kichi ws recv] ${data}`);
+    this.log("debug", `ws recv ${data}`);
     try {
       const msg = JSON.parse(data);
       this.tryResolvePendingRequest(msg);
@@ -428,7 +451,7 @@ export class KichiForwarderService {
         const joinAck = msg as JoinAckPayload;
         if (joinAck.success === false || !joinAck.authKey) {
           const failure = this.buildAckFailure(joinAck, "Join failed");
-          this.logger.warn(`Join failed: ${failure.error}`);
+          this.log("warn", `join failed: ${failure.error}`);
           this.joinResolve?.(failure);
           this.joinResolve = null;
           return;
@@ -437,24 +460,24 @@ export class KichiForwarderService {
         if (this.identity) {
           this.identity.authKey = joinAck.authKey;
           this.saveIdentity();
-          this.logger.info(`Joined as ${this.identity.avatarId}`);
+          this.log("info", `joined as ${this.identity.avatarId}`);
         }
         this.joinResolve?.({ success: true, authKey: joinAck.authKey });
         this.joinResolve = null;
       } else if (msg.type === "rejoin_failed" || msg.type === "auth_error") {
-        this.logger.warn(`Auth failed: ${msg.reason || "unknown"}`);
+        this.log("warn", `auth failed: ${msg.reason || "unknown"}`);
         this.clearAuthKey();
       } else if (msg.type === "leave_ack") {
         const leaveAck = msg as LeaveAckPayload;
         if (leaveAck.success === false) {
           const failure = this.buildAckFailure(leaveAck, "Leave failed");
-          this.logger.warn(`Leave failed: ${failure.error}`);
+          this.log("warn", `leave failed: ${failure.error}`);
         } else {
-          this.logger.info("Left Kichi world");
+          this.log("info", "left Kichi world");
         }
       }
     } catch (e) {
-      this.logger.warn(`Failed to parse message: ${e}`);
+      this.log("warn", `failed to parse message: ${e}`);
     }
   }
 
@@ -571,7 +594,7 @@ export class KichiForwarderService {
       }
       return null;
     } catch (e) {
-      this.logger.warn(`Failed to load identity: ${e}`);
+      this.log("warn", `failed to load identity: ${e}`);
       return null;
     }
   }
@@ -584,7 +607,7 @@ export class KichiForwarderService {
       if (!fs.existsSync(identityDir)) fs.mkdirSync(identityDir, { recursive: true, mode: 0o700 });
       fs.writeFileSync(identityPath, JSON.stringify(this.identity, null, 2), { mode: 0o600 });
     } catch (e) {
-      this.logger.error(`Failed to save identity: ${e}`);
+      this.log("error", `failed to save identity: ${e}`);
     }
   }
 
@@ -592,7 +615,7 @@ export class KichiForwarderService {
     if (!this.identity) return;
     this.identity.authKey = undefined;
     this.saveIdentity();
-    this.logger.info("AuthKey cleared");
+    this.log("info", "authKey cleared");
   }
 
   private sendRejoinPayload(): boolean {
@@ -603,7 +626,7 @@ export class KichiForwarderService {
     this.ws.send(
       JSON.stringify({ type: "rejoin", avatarId: this.identity.avatarId, authKey: this.identity.authKey }),
     );
-    this.logger.debug(`Sent rejoin for ${this.identity.avatarId}`);
+    this.log("debug", `sent rejoin for ${this.identity.avatarId}`);
     return true;
   }
 
@@ -628,7 +651,7 @@ export class KichiForwarderService {
     if (!this.host) {
       throw new Error("No Kichi host configured");
     }
-    return path.join(HOSTS_DIR, encodeURIComponent(this.host));
+    return path.join(this.options.runtimeDir, "hosts", encodeURIComponent(this.host));
   }
 
   private getWsUrl(): string {
@@ -647,14 +670,15 @@ export class KichiForwarderService {
 
   private loadCurrentHost(): string | null {
     try {
-      if (!fs.existsSync(STATE_PATH)) {
+      const statePath = this.getStatePath();
+      if (!fs.existsSync(statePath)) {
         return null;
       }
-      const data = JSON.parse(fs.readFileSync(STATE_PATH, "utf-8")) as { currentHost?: unknown };
+      const data = JSON.parse(fs.readFileSync(statePath, "utf-8")) as { currentHost?: unknown };
       if (typeof data.currentHost === "string" && data.currentHost.trim()) {
         return data.currentHost;
       }
-      throw new Error(`Invalid currentHost value in ${STATE_PATH}`);
+      throw new Error(`Invalid currentHost value in ${statePath}`);
     } catch (error) {
       throw new Error(`Failed to load current host: ${error}`);
     }
@@ -666,17 +690,18 @@ export class KichiForwarderService {
       currentHost: host,
       llmRuntimeEnabled: previousState?.llmRuntimeEnabled ?? DEFAULT_LLM_RUNTIME_ENABLED,
     };
-    fs.mkdirSync(KICHI_WORLD_DIR, { recursive: true, mode: 0o700 });
-    fs.writeFileSync(STATE_PATH, JSON.stringify(nextState, null, 2), { mode: 0o600 });
+    fs.mkdirSync(this.options.runtimeDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(this.getStatePath(), JSON.stringify(nextState, null, 2), { mode: 0o600 });
   }
 
   private readStateFile(): Partial<KichiState> | null {
-    if (!fs.existsSync(STATE_PATH)) {
+    const statePath = this.getStatePath();
+    if (!fs.existsSync(statePath)) {
       return null;
     }
-    const data = JSON.parse(fs.readFileSync(STATE_PATH, "utf-8")) as unknown;
+    const data = JSON.parse(fs.readFileSync(statePath, "utf-8")) as unknown;
     if (!data || typeof data !== "object") {
-      throw new Error(`Invalid state payload in ${STATE_PATH}`);
+      throw new Error(`Invalid state payload in ${statePath}`);
     }
     return data as Partial<KichiState>;
   }
@@ -699,4 +724,26 @@ export class KichiForwarderService {
     this.joinResolve({ success: false, error: reason });
     this.joinResolve = null;
   }
+
+  private logPrefix(): string {
+    return `[kichi:${this.options.agentId}]`;
+  }
+
+  private log(level: "debug" | "info" | "warn" | "error", message: string): void {
+    const formatted = `${this.logPrefix()} ${message}`;
+    switch (level) {
+      case "debug":
+        this.logger.debug(formatted);
+        return;
+      case "info":
+        this.logger.info(formatted);
+        return;
+      case "warn":
+        this.logger.warn(formatted);
+        return;
+      case "error":
+        this.logger.error(formatted);
+        return;
+    }
+  }
 }

package/src/types.ts

@@ -47,6 +47,9 @@ export type KichiIdentity = {
 };
 
 export type KichiConnectionStatus = {
+  agentId?: string;
+  runtimeDir?: string;
+  statePath?: string;
   host?: string;
   wsUrl?: string;
   identityPath?: string;