@nextclaw/service 0.2.12 → 0.2.14

package/dist/services/ui/local-ui-discovery.service.js

@@ -0,0 +1,43 @@
+import { isProcessRunning } from "../../utils/cli.utils.js";
+import { localUiRuntimeStore } from "../../stores/local-ui-runtime.store.js";
+import { managedServiceStateStore } from "../../stores/managed-service-state.store.js";
+import { resolveLocalUiBaseUrl } from "@nextclaw/core";
+//#region src/services/ui/local-ui-discovery.service.ts
+var LocalUiDiscoveryService = class {
+	constructor(localUiStore = localUiRuntimeStore, managedServiceStore = managedServiceStateStore, isProcessRunningFn = (pid) => isProcessRunning(pid)) {
+		this.localUiStore = localUiStore;
+		this.managedServiceStore = managedServiceStore;
+		this.isProcessRunningFn = isProcessRunningFn;
+	}
+	readRunningState = (state) => {
+		if (!state || !this.isProcessRunningFn(state.pid)) return null;
+		return state;
+	};
+	readRunningRuntimeState = () => {
+		return this.readRunningState(this.localUiStore.read()) ?? this.readRunningState(this.managedServiceStore.read());
+	};
+	resolveApiBase = () => {
+		const state = this.readRunningRuntimeState();
+		if (!state) return null;
+		if (typeof state.uiUrl === "string" && state.uiUrl.trim().length > 0) return state.uiUrl.replace(/\/+$/, "");
+		if (typeof state.apiUrl === "string" && state.apiUrl.trim().length > 0) return state.apiUrl.replace(/\/api\/?$/, "").replace(/\/+$/, "");
+		return null;
+	};
+	resolveLocalOrigin = (config) => {
+		const state = this.readRunningRuntimeState();
+		const runtimePort = state && typeof state.uiPort === "number" && Number.isFinite(state.uiPort) ? state.uiPort : null;
+		if (runtimePort !== null) return resolveLocalUiBaseUrl({
+			host: "0.0.0.0",
+			port: runtimePort
+		});
+		return resolveLocalUiBaseUrl({
+			host: "0.0.0.0",
+			port: typeof config.ui.port === "number" && Number.isFinite(config.ui.port) ? config.ui.port : 55667
+		});
+	};
+};
+const localUiDiscoveryService = new LocalUiDiscoveryService();
+//#endregion
+export { LocalUiDiscoveryService, localUiDiscoveryService };
+
+//# sourceMappingURL=local-ui-discovery.service.js.map

package/dist/services/ui/local-ui-discovery.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-ui-discovery.service.js","names":[],"sources":["../../../src/services/ui/local-ui-discovery.service.ts"],"sourcesContent":["import { resolveLocalUiBaseUrl, type Config } from \"@nextclaw/core\";\nimport { isProcessRunning } from \"@nextclaw-service/utils/cli.utils.js\";\nimport {\n  type LocalUiRuntimeState,\n  type LocalUiRuntimeStore,\n  localUiRuntimeStore\n} from \"@nextclaw-service/stores/local-ui-runtime.store.js\";\nimport {\n  type ManagedServiceState,\n  type ManagedServiceStateStore,\n  managedServiceStateStore\n} from \"@nextclaw-service/stores/managed-service-state.store.js\";\n\ntype DiscoveredLocalUiState = LocalUiRuntimeState | ManagedServiceState;\n\nexport class LocalUiDiscoveryService {\n  constructor(\n    private readonly localUiStore: LocalUiRuntimeStore = localUiRuntimeStore,\n    private readonly managedServiceStore: ManagedServiceStateStore = managedServiceStateStore,\n    private readonly isProcessRunningFn: (pid: number) => boolean = (pid) => isProcessRunning(pid)\n  ) {}\n\n  private readonly readRunningState = (state: DiscoveredLocalUiState | null): DiscoveredLocalUiState | null => {\n    if (!state || !this.isProcessRunningFn(state.pid)) {\n      return null;\n    }\n    return state;\n  };\n\n  readonly readRunningRuntimeState = (): DiscoveredLocalUiState | null => {\n    return this.readRunningState(this.localUiStore.read()) ?? this.readRunningState(this.managedServiceStore.read());\n  };\n\n  readonly resolveApiBase = (): string | null => {\n    const state = this.readRunningRuntimeState();\n    if (!state) {\n      return null;\n    }\n    if (typeof state.uiUrl === \"string\" && state.uiUrl.trim().length > 0) {\n      return state.uiUrl.replace(/\\/+$/, \"\");\n    }\n    if (typeof state.apiUrl === \"string\" && state.apiUrl.trim().length > 0) {\n      return state.apiUrl.replace(/\\/api\\/?$/, \"\").replace(/\\/+$/, \"\");\n    }\n    return null;\n  };\n\n  readonly resolveLocalOrigin = (config: Config): string => {\n    const state = this.readRunningRuntimeState();\n    const runtimePort =\n      state && typeof state.uiPort === \"number\" && Number.isFinite(state.uiPort)\n        ? state.uiPort\n        : null;\n    if (runtimePort !== null) {\n      return resolveLocalUiBaseUrl({ host: \"0.0.0.0\", port: runtimePort });\n    }\n    const port = typeof config.ui.port === \"number\" && Number.isFinite(config.ui.port) ? config.ui.port : 55667;\n    return resolveLocalUiBaseUrl({ host: \"0.0.0.0\", port });\n  };\n}\n\nexport const localUiDiscoveryService = new LocalUiDiscoveryService();\n"],"mappings":";;;;;AAeA,IAAa,0BAAb,MAAqC;CACnC,YACE,eAAqD,qBACrD,sBAAiE,0BACjE,sBAAiE,QAAQ,iBAAiB,IAAI,EAC9F;AAHiB,OAAA,eAAA;AACA,OAAA,sBAAA;AACA,OAAA,qBAAA;;CAGnB,oBAAqC,UAAwE;AAC3G,MAAI,CAAC,SAAS,CAAC,KAAK,mBAAmB,MAAM,IAAI,CAC/C,QAAO;AAET,SAAO;;CAGT,gCAAwE;AACtE,SAAO,KAAK,iBAAiB,KAAK,aAAa,MAAM,CAAC,IAAI,KAAK,iBAAiB,KAAK,oBAAoB,MAAM,CAAC;;CAGlH,uBAA+C;EAC7C,MAAM,QAAQ,KAAK,yBAAyB;AAC5C,MAAI,CAAC,MACH,QAAO;AAET,MAAI,OAAO,MAAM,UAAU,YAAY,MAAM,MAAM,MAAM,CAAC,SAAS,EACjE,QAAO,MAAM,MAAM,QAAQ,QAAQ,GAAG;AAExC,MAAI,OAAO,MAAM,WAAW,YAAY,MAAM,OAAO,MAAM,CAAC,SAAS,EACnE,QAAO,MAAM,OAAO,QAAQ,aAAa,GAAG,CAAC,QAAQ,QAAQ,GAAG;AAElE,SAAO;;CAGT,sBAA+B,WAA2B;EACxD,MAAM,QAAQ,KAAK,yBAAyB;EAC5C,MAAM,cACJ,SAAS,OAAO,MAAM,WAAW,YAAY,OAAO,SAAS,MAAM,OAAO,GACtE,MAAM,SACN;AACN,MAAI,gBAAgB,KAClB,QAAO,sBAAsB;GAAE,MAAM;GAAW,MAAM;GAAa,CAAC;AAGtE,SAAO,sBAAsB;GAAE,MAAM;GAAW,MADnC,OAAO,OAAO,GAAG,SAAS,YAAY,OAAO,SAAS,OAAO,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO;GAChD,CAAC;;;AAI3D,MAAa,0BAA0B,IAAI,yBAAyB"}

package/dist/services/ui/runtime-control-host.service.d.ts

@@ -0,0 +1,29 @@
+import { RequestRestartParams } from "../../types/cli.types.js";
+import { Config } from "@nextclaw/core";
+import { RuntimeControlActionResult, RuntimeControlView, UiRuntimeControlHost } from "@nextclaw/server";
+
+//#region src/services/ui/runtime-control-host.service.d.ts
+type RuntimeControlHostDeps = {
+  serviceCommands: {
+    startService: (options: {
+      uiOverrides: Record<string, unknown>;
+      open: boolean;
+    }) => Promise<void>;
+    stopService: () => Promise<void>;
+  };
+  requestRestart: (params: RequestRestartParams) => Promise<void>;
+  uiConfig: Pick<Config["ui"], "host" | "port">;
+};
+declare class RuntimeControlHost implements UiRuntimeControlHost {
+  private readonly deps;
+  constructor(deps: RuntimeControlHostDeps);
+  getControl: () => RuntimeControlView;
+  startService: () => Promise<RuntimeControlActionResult>;
+  restartService: () => Promise<RuntimeControlActionResult>;
+  stopService: () => Promise<RuntimeControlActionResult>;
+  private createServiceControlDeps;
+}
+declare function createRuntimeControlHost(params: RuntimeControlHostDeps): RuntimeControlHost;
+//#endregion
+export { RuntimeControlHost, createRuntimeControlHost };
+//# sourceMappingURL=runtime-control-host.service.d.ts.map

package/dist/services/ui/runtime-control-host.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-control-host.service.d.ts","names":[],"sources":["../../../src/services/ui/runtime-control-host.service.ts"],"mappings":";;;;;KAWK,sBAAA;EACH,eAAA;IACE,YAAA,GAAe,OAAA;MAAW,WAAA,EAAa,MAAA;MAAyB,IAAA;IAAA,MAAoB,OAAA;IACpF,WAAA,QAAmB,OAAA;EAAA;EAErB,cAAA,GAAiB,MAAA,EAAQ,oBAAA,KAAyB,OAAA;EAClD,QAAA,EAAU,IAAA,CAAK,MAAA;AAAA;AAAA,cAGJ,kBAAA,YAA8B,oBAAA;EAAA,iBACZ,IAAA;cAAA,IAAA,EAAM,sBAAA;EAEnC,UAAA,QAAiB,kBAAA;EA0CjB,YAAA,QAAyB,OAAA,CAAQ,0BAAA;EAUjC,cAAA,QAA2B,OAAA,CAAQ,0BAAA;EAUnC,WAAA,QAAwB,OAAA,CAAQ,0BAAA;EAAA,QAUxB,wBAAA;AAAA;AAAA,iBAUM,wBAAA,CAAyB,MAAA,EAAQ,sBAAA,GAAyB,kBAAA"}

package/dist/services/ui/runtime-control-host.service.js

@@ -0,0 +1,91 @@
+import { controlRemoteService, resolveRemoteServiceView } from "../remote/remote-service-control.service.js";
+import { requestManagedServiceRestart } from "./service-remote-access.service.js";
+import { pendingRestartStore } from "../../stores/pending-restart.store.js";
+//#region src/services/ui/runtime-control-host.service.ts
+const MANAGED_SERVICE_OWNER_LABEL = "Managed local service";
+const DESKTOP_APP_ONLY_REASON = "App restart is only available in the desktop shell.";
+const RUNNING_PAGE_START_REASON = "This page is already hosted by the running local service.";
+var RuntimeControlHost = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	getControl = () => {
+		const service = resolveRemoteServiceView(this.deps.uiConfig);
+		const serviceRunning = service.running;
+		const pendingRestart = pendingRestartStore.read();
+		return {
+			environment: "managed-local-service",
+			lifecycle: serviceRunning ? "healthy" : "unavailable",
+			serviceState: serviceRunning ? "running" : "stopped",
+			canStartService: {
+				available: !serviceRunning,
+				requiresConfirmation: false,
+				impact: "brief-ui-disconnect",
+				...serviceRunning ? { reasonIfUnavailable: RUNNING_PAGE_START_REASON } : {}
+			},
+			canRestartService: {
+				available: serviceRunning,
+				requiresConfirmation: false,
+				impact: "brief-ui-disconnect",
+				...!serviceRunning ? { reasonIfUnavailable: "The local service is not running." } : {}
+			},
+			canStopService: {
+				available: serviceRunning,
+				requiresConfirmation: true,
+				impact: "brief-ui-disconnect",
+				...!serviceRunning ? { reasonIfUnavailable: "The local service is already stopped." } : {}
+			},
+			canRestartApp: {
+				available: false,
+				requiresConfirmation: true,
+				impact: "full-app-relaunch",
+				reasonIfUnavailable: DESKTOP_APP_ONLY_REASON
+			},
+			pendingRestart,
+			ownerLabel: MANAGED_SERVICE_OWNER_LABEL,
+			managementHint: service.currentProcess ? "This page is served by the running local service. Closing the browser does not stop it." : "Manage the local NextClaw service from this page without tying service lifecycle to the browser tab.",
+			message: "Use this page to manage the local NextClaw service. Closing the browser does not stop the service."
+		};
+	};
+	startService = async () => {
+		const result = await controlRemoteService("start", this.createServiceControlDeps());
+		return {
+			accepted: result.accepted,
+			action: "start-service",
+			lifecycle: "starting-service",
+			message: result.message
+		};
+	};
+	restartService = async () => {
+		const result = await controlRemoteService("restart", this.createServiceControlDeps());
+		return {
+			accepted: result.accepted,
+			action: "restart-service",
+			lifecycle: "restarting-service",
+			message: result.message
+		};
+	};
+	stopService = async () => {
+		const result = await controlRemoteService("stop", this.createServiceControlDeps());
+		return {
+			accepted: result.accepted,
+			action: "stop-service",
+			lifecycle: "stopping-service",
+			message: result.message
+		};
+	};
+	createServiceControlDeps = () => {
+		return {
+			serviceCommands: this.deps.serviceCommands,
+			requestManagedServiceRestart: () => requestManagedServiceRestart(this.deps.requestRestart, { uiPort: this.deps.uiConfig.port }),
+			currentUi: this.deps.uiConfig
+		};
+	};
+};
+function createRuntimeControlHost(params) {
+	return new RuntimeControlHost(params);
+}
+//#endregion
+export { RuntimeControlHost, createRuntimeControlHost };
+
+//# sourceMappingURL=runtime-control-host.service.js.map

package/dist/services/ui/runtime-control-host.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-control-host.service.js","names":[],"sources":["../../../src/services/ui/runtime-control-host.service.ts"],"sourcesContent":["import type { Config } from \"@nextclaw/core\";\nimport type { RuntimeControlActionResult, RuntimeControlView, UiRuntimeControlHost } from \"@nextclaw/server\";\nimport { requestManagedServiceRestart } from \"@nextclaw-service/services/ui/service-remote-access.service.js\";\nimport { controlRemoteService, resolveRemoteServiceView } from \"@nextclaw-service/services/remote/remote-service-control.service.js\";\nimport type { RequestRestartParams } from \"@nextclaw-service/types/cli.types.js\";\nimport { pendingRestartStore } from \"@nextclaw-service/stores/pending-restart.store.js\";\n\nconst MANAGED_SERVICE_OWNER_LABEL = \"Managed local service\";\nconst DESKTOP_APP_ONLY_REASON = \"App restart is only available in the desktop shell.\";\nconst RUNNING_PAGE_START_REASON = \"This page is already hosted by the running local service.\";\n\ntype RuntimeControlHostDeps = {\n  serviceCommands: {\n    startService: (options: { uiOverrides: Record<string, unknown>; open: boolean }) => Promise<void>;\n    stopService: () => Promise<void>;\n  };\n  requestRestart: (params: RequestRestartParams) => Promise<void>;\n  uiConfig: Pick<Config[\"ui\"], \"host\" | \"port\">;\n};\n\nexport class RuntimeControlHost implements UiRuntimeControlHost {\n  constructor(private readonly deps: RuntimeControlHostDeps) {}\n\n  getControl = (): RuntimeControlView => {\n    const service = resolveRemoteServiceView(this.deps.uiConfig);\n    const serviceRunning = service.running;\n    const pendingRestart = pendingRestartStore.read();\n\n    return {\n      environment: \"managed-local-service\",\n      lifecycle: serviceRunning ? \"healthy\" : \"unavailable\",\n      serviceState: serviceRunning ? \"running\" : \"stopped\",\n      canStartService: {\n        available: !serviceRunning,\n        requiresConfirmation: false,\n        impact: \"brief-ui-disconnect\",\n        ...(serviceRunning ? { reasonIfUnavailable: RUNNING_PAGE_START_REASON } : {})\n      },\n      canRestartService: {\n        available: serviceRunning,\n        requiresConfirmation: false,\n        impact: \"brief-ui-disconnect\",\n        ...(!serviceRunning ? { reasonIfUnavailable: \"The local service is not running.\" } : {})\n      },\n      canStopService: {\n        available: serviceRunning,\n        requiresConfirmation: true,\n        impact: \"brief-ui-disconnect\",\n        ...(!serviceRunning ? { reasonIfUnavailable: \"The local service is already stopped.\" } : {})\n      },\n      canRestartApp: {\n        available: false,\n        requiresConfirmation: true,\n        impact: \"full-app-relaunch\",\n        reasonIfUnavailable: DESKTOP_APP_ONLY_REASON\n      },\n      pendingRestart,\n      ownerLabel: MANAGED_SERVICE_OWNER_LABEL,\n      managementHint: service.currentProcess\n        ? \"This page is served by the running local service. Closing the browser does not stop it.\"\n        : \"Manage the local NextClaw service from this page without tying service lifecycle to the browser tab.\",\n      message: \"Use this page to manage the local NextClaw service. Closing the browser does not stop the service.\"\n    };\n  };\n\n  startService = async (): Promise<RuntimeControlActionResult> => {\n    const result = await controlRemoteService(\"start\", this.createServiceControlDeps());\n    return {\n      accepted: result.accepted,\n      action: \"start-service\",\n      lifecycle: \"starting-service\",\n      message: result.message\n    };\n  };\n\n  restartService = async (): Promise<RuntimeControlActionResult> => {\n    const result = await controlRemoteService(\"restart\", this.createServiceControlDeps());\n    return {\n      accepted: result.accepted,\n      action: \"restart-service\",\n      lifecycle: \"restarting-service\",\n      message: result.message\n    };\n  };\n\n  stopService = async (): Promise<RuntimeControlActionResult> => {\n    const result = await controlRemoteService(\"stop\", this.createServiceControlDeps());\n    return {\n      accepted: result.accepted,\n      action: \"stop-service\",\n      lifecycle: \"stopping-service\",\n      message: result.message\n    };\n  };\n\n  private createServiceControlDeps = () => {\n    return {\n      serviceCommands: this.deps.serviceCommands,\n      requestManagedServiceRestart: () =>\n        requestManagedServiceRestart(this.deps.requestRestart, { uiPort: this.deps.uiConfig.port }),\n      currentUi: this.deps.uiConfig\n    };\n  };\n}\n\nexport function createRuntimeControlHost(params: RuntimeControlHostDeps): RuntimeControlHost {\n  return new RuntimeControlHost(params);\n}\n"],"mappings":";;;;AAOA,MAAM,8BAA8B;AACpC,MAAM,0BAA0B;AAChC,MAAM,4BAA4B;AAWlC,IAAa,qBAAb,MAAgE;CAC9D,YAAY,MAA+C;AAA9B,OAAA,OAAA;;CAE7B,mBAAuC;EACrC,MAAM,UAAU,yBAAyB,KAAK,KAAK,SAAS;EAC5D,MAAM,iBAAiB,QAAQ;EAC/B,MAAM,iBAAiB,oBAAoB,MAAM;AAEjD,SAAO;GACL,aAAa;GACb,WAAW,iBAAiB,YAAY;GACxC,cAAc,iBAAiB,YAAY;GAC3C,iBAAiB;IACf,WAAW,CAAC;IACZ,sBAAsB;IACtB,QAAQ;IACR,GAAI,iBAAiB,EAAE,qBAAqB,2BAA2B,GAAG,EAAE;IAC7E;GACD,mBAAmB;IACjB,WAAW;IACX,sBAAsB;IACtB,QAAQ;IACR,GAAI,CAAC,iBAAiB,EAAE,qBAAqB,qCAAqC,GAAG,EAAE;IACxF;GACD,gBAAgB;IACd,WAAW;IACX,sBAAsB;IACtB,QAAQ;IACR,GAAI,CAAC,iBAAiB,EAAE,qBAAqB,yCAAyC,GAAG,EAAE;IAC5F;GACD,eAAe;IACb,WAAW;IACX,sBAAsB;IACtB,QAAQ;IACR,qBAAqB;IACtB;GACD;GACA,YAAY;GACZ,gBAAgB,QAAQ,iBACpB,4FACA;GACJ,SAAS;GACV;;CAGH,eAAe,YAAiD;EAC9D,MAAM,SAAS,MAAM,qBAAqB,SAAS,KAAK,0BAA0B,CAAC;AACnF,SAAO;GACL,UAAU,OAAO;GACjB,QAAQ;GACR,WAAW;GACX,SAAS,OAAO;GACjB;;CAGH,iBAAiB,YAAiD;EAChE,MAAM,SAAS,MAAM,qBAAqB,WAAW,KAAK,0BAA0B,CAAC;AACrF,SAAO;GACL,UAAU,OAAO;GACjB,QAAQ;GACR,WAAW;GACX,SAAS,OAAO;GACjB;;CAGH,cAAc,YAAiD;EAC7D,MAAM,SAAS,MAAM,qBAAqB,QAAQ,KAAK,0BAA0B,CAAC;AAClF,SAAO;GACL,UAAU,OAAO;GACjB,QAAQ;GACR,WAAW;GACX,SAAS,OAAO;GACjB;;CAGH,iCAAyC;AACvC,SAAO;GACL,iBAAiB,KAAK,KAAK;GAC3B,oCACE,6BAA6B,KAAK,KAAK,gBAAgB,EAAE,QAAQ,KAAK,KAAK,SAAS,MAAM,CAAC;GAC7F,WAAW,KAAK,KAAK;GACtB;;;AAIL,SAAgB,yBAAyB,QAAoD;AAC3F,QAAO,IAAI,mBAAmB,OAAO"}

package/dist/services/ui/service-remote-access.service.d.ts

@@ -0,0 +1,26 @@
+import { RequestRestartParams } from "../../types/cli.types.js";
+import { RemoteAccessHost } from "../remote/remote-access-host.service.js";
+import { Config } from "@nextclaw/core";
+import { RemoteServiceModule } from "@nextclaw/remote";
+
+//#region src/services/ui/service-remote-access.service.d.ts
+type ManagedServiceRestartOptions = {
+  uiPort?: number;
+  reason?: string;
+};
+declare function requestManagedServiceRestart(requestRestart: (params: RequestRestartParams) => Promise<void>, options?: ManagedServiceRestartOptions): Promise<void>;
+declare function createRemoteAccessHost(params: {
+  serviceCommands: {
+    startService: (options: {
+      uiOverrides: Record<string, unknown>;
+      open: boolean;
+    }) => Promise<void>;
+    stopService: () => Promise<void>;
+  };
+  requestRestart: (params: RequestRestartParams) => Promise<void>;
+  uiConfig: Pick<Config["ui"], "host" | "port">;
+  remoteModule: RemoteServiceModule | null;
+}): RemoteAccessHost;
+//#endregion
+export { createRemoteAccessHost, requestManagedServiceRestart };
+//# sourceMappingURL=service-remote-access.service.d.ts.map

package/dist/services/ui/service-remote-access.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-remote-access.service.d.ts","names":[],"sources":["../../../src/services/ui/service-remote-access.service.ts"],"mappings":";;;;;;KAOK,4BAAA;EACH,MAAA;EACA,MAAA;AAAA;AAAA,iBAGc,4BAAA,CACd,cAAA,GAAiB,MAAA,EAAQ,oBAAA,KAAyB,OAAA,QAClD,OAAA,GAAS,4BAAA,GACR,OAAA;AAAA,iBAgBa,sBAAA,CAAuB,MAAA;EACrC,eAAA;IACE,YAAA,GAAe,OAAA;MAAW,WAAA,EAAa,MAAA;MAAyB,IAAA;IAAA,MAAoB,OAAA;IACpF,WAAA,QAAmB,OAAA;EAAA;EAErB,cAAA,GAAiB,MAAA,EAAQ,oBAAA,KAAyB,OAAA;EAClD,QAAA,EAAU,IAAA,CAAK,MAAA;EACf,YAAA,EAAc,mBAAA;AAAA,IACZ,gBAAA"}

package/dist/services/ui/service-remote-access.service.js

@@ -0,0 +1,40 @@
+import { RemoteAccessHost } from "../remote/remote-access-host.service.js";
+import { RemoteCommands } from "../../controllers/commands/remote-command.controller.js";
+import { PlatformAuthCommands } from "../platform-auth/platform-auth-commands.service.js";
+import "../../controllers/commands/platform-auth-command.controller.js";
+//#region src/services/ui/service-remote-access.service.ts
+function requestManagedServiceRestart(requestRestart, options = {}) {
+	const uiPort = typeof options.uiPort === "number" && Number.isFinite(options.uiPort) ? Math.floor(options.uiPort) : void 0;
+	return requestRestart({
+		reason: options.reason?.trim() || "remote access service restart",
+		manualMessage: uiPort ? `Restart the managed service to restore the UI on port ${uiPort}.` : "Restart the managed service to restore the UI.",
+		strategy: "background-service-or-exit",
+		delayMs: 500,
+		silentOnServiceRestart: true
+	});
+}
+function createRemoteAccessHost(params) {
+	const { remoteModule, requestRestart, serviceCommands, uiConfig } = params;
+	return new RemoteAccessHost({
+		serviceCommands,
+		requestManagedServiceRestart: (options) => requestManagedServiceRestart(requestRestart, options),
+		remoteCommands: new RemoteCommands({ currentLocalOrigin: `http://127.0.0.1:${uiConfig.port}` }),
+		platformAuthCommands: new PlatformAuthCommands(),
+		currentUi: uiConfig,
+		remoteRuntimeController: remoteModule ? {
+			start: async () => {
+				remoteModule?.start();
+			},
+			stop: async () => {
+				await remoteModule?.stop();
+			},
+			restart: async () => {
+				await remoteModule?.restart();
+			}
+		} : null
+	});
+}
+//#endregion
+export { createRemoteAccessHost, requestManagedServiceRestart };
+
+//# sourceMappingURL=service-remote-access.service.js.map

package/dist/services/ui/service-remote-access.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-remote-access.service.js","names":[],"sources":["../../../src/services/ui/service-remote-access.service.ts"],"sourcesContent":["import type { Config } from \"@nextclaw/core\";\nimport type { RemoteServiceModule } from \"@nextclaw/remote\";\nimport type { RequestRestartParams } from \"@nextclaw-service/types/cli.types.js\";\nimport { RemoteAccessHost } from \"@nextclaw-service/services/remote/remote-access-host.service.js\";\nimport { PlatformAuthCommands } from \"@nextclaw-service/controllers/commands/platform-auth-command.controller.js\";\nimport { RemoteCommands } from \"@nextclaw-service/controllers/commands/remote-command.controller.js\";\n\ntype ManagedServiceRestartOptions = {\n  uiPort?: number;\n  reason?: string;\n};\n\nexport function requestManagedServiceRestart(\n  requestRestart: (params: RequestRestartParams) => Promise<void>,\n  options: ManagedServiceRestartOptions = {}\n): Promise<void> {\n  const uiPort =\n    typeof options.uiPort === \"number\" && Number.isFinite(options.uiPort) ? Math.floor(options.uiPort) : undefined;\n  const reason = options.reason?.trim() || \"remote access service restart\";\n  const manualMessage = uiPort\n    ? `Restart the managed service to restore the UI on port ${uiPort}.`\n    : \"Restart the managed service to restore the UI.\";\n  return requestRestart({\n    reason,\n    manualMessage,\n    strategy: \"background-service-or-exit\",\n    delayMs: 500,\n    silentOnServiceRestart: true\n  });\n}\n\nexport function createRemoteAccessHost(params: {\n  serviceCommands: {\n    startService: (options: { uiOverrides: Record<string, unknown>; open: boolean }) => Promise<void>;\n    stopService: () => Promise<void>;\n  };\n  requestRestart: (params: RequestRestartParams) => Promise<void>;\n  uiConfig: Pick<Config[\"ui\"], \"host\" | \"port\">;\n  remoteModule: RemoteServiceModule | null;\n}): RemoteAccessHost {\n  const { remoteModule, requestRestart, serviceCommands, uiConfig } = params;\n  const currentLocalOrigin = `http://127.0.0.1:${uiConfig.port}`;\n  return new RemoteAccessHost({\n    serviceCommands,\n    requestManagedServiceRestart: (options?: ManagedServiceRestartOptions) => requestManagedServiceRestart(requestRestart, options),\n    remoteCommands: new RemoteCommands({ currentLocalOrigin }),\n    platformAuthCommands: new PlatformAuthCommands(),\n    currentUi: uiConfig,\n    remoteRuntimeController: remoteModule\n      ? {\n        start: async () => {\n          remoteModule?.start();\n        },\n        stop: async () => {\n          await remoteModule?.stop();\n        },\n        restart: async () => {\n          await remoteModule?.restart();\n        }\n      }\n      : null\n  });\n}\n"],"mappings":";;;;;AAYA,SAAgB,6BACd,gBACA,UAAwC,EAAE,EAC3B;CACf,MAAM,SACJ,OAAO,QAAQ,WAAW,YAAY,OAAO,SAAS,QAAQ,OAAO,GAAG,KAAK,MAAM,QAAQ,OAAO,GAAG,KAAA;AAKvG,QAAO,eAAe;EACpB,QALa,QAAQ,QAAQ,MAAM,IAAI;EAMvC,eALoB,SAClB,yDAAyD,OAAO,KAChE;EAIF,UAAU;EACV,SAAS;EACT,wBAAwB;EACzB,CAAC;;AAGJ,SAAgB,uBAAuB,QAQlB;CACnB,MAAM,EAAE,cAAc,gBAAgB,iBAAiB,aAAa;AAEpE,QAAO,IAAI,iBAAiB;EAC1B;EACA,+BAA+B,YAA2C,6BAA6B,gBAAgB,QAAQ;EAC/H,gBAAgB,IAAI,eAAe,EAAE,oBAJZ,oBAAoB,SAAS,QAIG,CAAC;EAC1D,sBAAsB,IAAI,sBAAsB;EAChD,WAAW;EACX,yBAAyB,eACrB;GACA,OAAO,YAAY;AACjB,kBAAc,OAAO;;GAEvB,MAAM,YAAY;AAChB,UAAM,cAAc,MAAM;;GAE5B,SAAS,YAAY;AACnB,UAAM,cAAc,SAAS;;GAEhC,GACC;EACL,CAAC"}

package/dist/services/ui/ui-bridge-api.service.d.ts

@@ -0,0 +1,17 @@
+//#region src/services/ui/ui-bridge-api.service.d.ts
+type UiBridgeApiMethod = "GET" | "POST" | "PUT" | "DELETE";
+declare function resolveLocalUiApiBase(): string | null;
+declare class UiBridgeApiClient {
+  private readonly apiBase;
+  private cookie;
+  constructor(apiBase: string);
+  private readonly getCookie;
+  readonly request: <T>(params: {
+    path: string;
+    method?: UiBridgeApiMethod;
+    body?: unknown;
+  }) => Promise<T>;
+}
+//#endregion
+export { UiBridgeApiClient, UiBridgeApiMethod, resolveLocalUiApiBase };
+//# sourceMappingURL=ui-bridge-api.service.d.ts.map

package/dist/services/ui/ui-bridge-api.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-bridge-api.service.d.ts","names":[],"sources":["../../../src/services/ui/ui-bridge-api.service.ts"],"mappings":";KAiBY,iBAAA;AAAA,iBAEI,qBAAA,CAAA;AAAA,cAIH,iBAAA;EAAA,iBAGkB,OAAA;EAAA,QAFrB,MAAA;cAEqB,OAAA;EAAA,iBAEZ,SAAA;EAAA,SAyBR,OAAA,MAAoB,MAAA;IAC3B,IAAA;IACA,MAAA,GAAS,iBAAA;IACT,IAAA;EAAA,MACE,OAAA,CAAQ,CAAA;AAAA"}

package/dist/services/ui/ui-bridge-api.service.js

@@ -0,0 +1,45 @@
+import { localUiDiscoveryService } from "./local-ui-discovery.service.js";
+import { ensureUiBridgeSecret } from "@nextclaw/server";
+//#region src/services/ui/ui-bridge-api.service.ts
+function resolveLocalUiApiBase() {
+	return localUiDiscoveryService.resolveApiBase();
+}
+var UiBridgeApiClient = class {
+	cookie;
+	constructor(apiBase) {
+		this.apiBase = apiBase;
+	}
+	getCookie = async () => {
+		if (this.cookie !== void 0) return this.cookie;
+		const bridgeSecret = ensureUiBridgeSecret();
+		const response = await fetch(`${this.apiBase}/api/auth/bridge`, {
+			method: "POST",
+			headers: { "x-nextclaw-ui-bridge-secret": bridgeSecret }
+		});
+		if (!response.ok) throw new Error(`bridge auth failed with status ${response.status}`);
+		const payload = await response.json();
+		if (!payload.ok) throw new Error(payload.error?.message ?? "bridge auth failed");
+		this.cookie = typeof payload.data.cookie === "string" && payload.data.cookie.trim() ? payload.data.cookie.trim() : null;
+		return this.cookie;
+	};
+	request = async (params) => {
+		const { body, method, path } = params;
+		const cookie = await this.getCookie();
+		const response = await fetch(`${this.apiBase}${path}`, {
+			method: method ?? "GET",
+			headers: {
+				...body ? { "Content-Type": "application/json" } : {},
+				...cookie ? { Cookie: cookie } : {}
+			},
+			...body ? { body: JSON.stringify(body) } : {}
+		});
+		if (!response.ok) throw new Error(`api request failed with status ${response.status}`);
+		const payload = await response.json();
+		if (!payload.ok) throw new Error(payload.error?.message ?? "api request failed");
+		return payload.data;
+	};
+};
+//#endregion
+export { UiBridgeApiClient, resolveLocalUiApiBase };
+
+//# sourceMappingURL=ui-bridge-api.service.js.map

package/dist/services/ui/ui-bridge-api.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-bridge-api.service.js","names":[],"sources":["../../../src/services/ui/ui-bridge-api.service.ts"],"sourcesContent":["import { ensureUiBridgeSecret } from \"@nextclaw/server\";\nimport { localUiDiscoveryService } from \"./local-ui-discovery.service.js\";\n\ntype ApiOkResponse<T> = {\n  ok: true;\n  data: T;\n};\n\ntype ApiErrorResponse = {\n  ok: false;\n  error?: {\n    message?: string;\n  };\n};\n\ntype ApiResponse<T> = ApiOkResponse<T> | ApiErrorResponse;\n\nexport type UiBridgeApiMethod = \"GET\" | \"POST\" | \"PUT\" | \"DELETE\";\n\nexport function resolveLocalUiApiBase(): string | null {\n  return localUiDiscoveryService.resolveApiBase();\n}\n\nexport class UiBridgeApiClient {\n  private cookie: string | null | undefined;\n\n  constructor(private readonly apiBase: string) {}\n\n  private readonly getCookie = async (): Promise<string | null> => {\n    if (this.cookie !== undefined) {\n      return this.cookie;\n    }\n    const bridgeSecret = ensureUiBridgeSecret();\n    const response = await fetch(`${this.apiBase}/api/auth/bridge`, {\n      method: \"POST\",\n      headers: {\n        \"x-nextclaw-ui-bridge-secret\": bridgeSecret\n      }\n    });\n    if (!response.ok) {\n      throw new Error(`bridge auth failed with status ${response.status}`);\n    }\n    const payload = (await response.json()) as ApiResponse<{ cookie?: string | null }>;\n    if (!payload.ok) {\n      throw new Error(payload.error?.message ?? \"bridge auth failed\");\n    }\n    this.cookie =\n      typeof payload.data.cookie === \"string\" && payload.data.cookie.trim()\n        ? payload.data.cookie.trim()\n        : null;\n    return this.cookie;\n  };\n\n  readonly request = async <T>(params: {\n    path: string;\n    method?: UiBridgeApiMethod;\n    body?: unknown;\n  }): Promise<T> => {\n    const { body, method, path } = params;\n    const cookie = await this.getCookie();\n    const response = await fetch(`${this.apiBase}${path}`, {\n      method: method ?? \"GET\",\n      headers: {\n        ...(body ? { \"Content-Type\": \"application/json\" } : {}),\n        ...(cookie ? { Cookie: cookie } : {})\n      },\n      ...(body ? { body: JSON.stringify(body) } : {})\n    });\n    if (!response.ok) {\n      throw new Error(`api request failed with status ${response.status}`);\n    }\n    const payload = (await response.json()) as ApiResponse<T>;\n    if (!payload.ok) {\n      throw new Error(payload.error?.message ?? \"api request failed\");\n    }\n    return payload.data;\n  };\n}\n"],"mappings":";;;AAmBA,SAAgB,wBAAuC;AACrD,QAAO,wBAAwB,gBAAgB;;AAGjD,IAAa,oBAAb,MAA+B;CAC7B;CAEA,YAAY,SAAkC;AAAjB,OAAA,UAAA;;CAE7B,YAA6B,YAAoC;AAC/D,MAAI,KAAK,WAAW,KAAA,EAClB,QAAO,KAAK;EAEd,MAAM,eAAe,sBAAsB;EAC3C,MAAM,WAAW,MAAM,MAAM,GAAG,KAAK,QAAQ,mBAAmB;GAC9D,QAAQ;GACR,SAAS,EACP,+BAA+B,cAChC;GACF,CAAC;AACF,MAAI,CAAC,SAAS,GACZ,OAAM,IAAI,MAAM,kCAAkC,SAAS,SAAS;EAEtE,MAAM,UAAW,MAAM,SAAS,MAAM;AACtC,MAAI,CAAC,QAAQ,GACX,OAAM,IAAI,MAAM,QAAQ,OAAO,WAAW,qBAAqB;AAEjE,OAAK,SACH,OAAO,QAAQ,KAAK,WAAW,YAAY,QAAQ,KAAK,OAAO,MAAM,GACjE,QAAQ,KAAK,OAAO,MAAM,GAC1B;AACN,SAAO,KAAK;;CAGd,UAAmB,OAAU,WAIX;EAChB,MAAM,EAAE,MAAM,QAAQ,SAAS;EAC/B,MAAM,SAAS,MAAM,KAAK,WAAW;EACrC,MAAM,WAAW,MAAM,MAAM,GAAG,KAAK,UAAU,QAAQ;GACrD,QAAQ,UAAU;GAClB,SAAS;IACP,GAAI,OAAO,EAAE,gBAAgB,oBAAoB,GAAG,EAAE;IACtD,GAAI,SAAS,EAAE,QAAQ,QAAQ,GAAG,EAAE;IACrC;GACD,GAAI,OAAO,EAAE,MAAM,KAAK,UAAU,KAAK,EAAE,GAAG,EAAE;GAC/C,CAAC;AACF,MAAI,CAAC,SAAS,GACZ,OAAM,IAAI,MAAM,kCAAkC,SAAS,SAAS;EAEtE,MAAM,UAAW,MAAM,SAAS,MAAM;AACtC,MAAI,CAAC,QAAQ,GACX,OAAM,IAAI,MAAM,QAAQ,OAAO,WAAW,qBAAqB;AAEjE,SAAO,QAAQ"}

package/dist/services/usage/llm-usage-command.service.d.ts

@@ -0,0 +1,21 @@
+import { UsageCommandOptions } from "../../types/cli.types.js";
+import { LlmUsageManager } from "@nextclaw/kernel";
+
+//#region src/services/usage/llm-usage-command.service.d.ts
+declare class LlmUsageCommandService {
+  private readonly usageManager;
+  constructor(deps?: {
+    usageManager?: LlmUsageManager;
+  });
+  readonly show: (opts?: UsageCommandOptions) => Promise<void>;
+  private readonly showSnapshot;
+  private readonly showHistory;
+  private readonly showStats;
+  private readonly renderSnapshot;
+  private readonly renderHistory;
+  private readonly renderStats;
+  private readonly toPercent;
+}
+//#endregion
+export { LlmUsageCommandService };
+//# sourceMappingURL=llm-usage-command.service.d.ts.map

package/dist/services/usage/llm-usage-command.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-usage-command.service.d.ts","names":[],"sources":["../../../src/services/usage/llm-usage-command.service.ts"],"mappings":";;;;cAMa,sBAAA;EAAA,iBACM,YAAA;cAEL,IAAA;IACV,YAAA,GAAe,eAAA;EAAA;EAAA,SAKR,IAAA,GAAc,IAAA,GAAM,mBAAA,KAA2B,OAAA;EAAA,iBAiBvC,YAAA;EAAA,iBAoBA,WAAA;EAAA,iBA0BA,SAAA;EAAA,iBAoBA,cAAA;EAAA,iBAsBA,aAAA;EAAA,iBAeA,WAAA;EAAA,iBA0BA,SAAA;AAAA"}

package/dist/services/usage/llm-usage-command.service.js

@@ -0,0 +1,152 @@
+import { LlmUsageManager } from "@nextclaw/kernel";
+//#region src/services/usage/llm-usage-command.service.ts
+var LlmUsageCommandService = class {
+	usageManager;
+	constructor(deps = {}) {
+		this.usageManager = deps.usageManager ?? new LlmUsageManager();
+	}
+	show = async (opts = {}) => {
+		if (opts.history && opts.stats) {
+			console.error("Choose only one usage mode: `--history` or `--stats`.");
+			process.exitCode = 1;
+			return;
+		}
+		if (opts.history) {
+			this.showHistory(opts);
+			return;
+		}
+		if (opts.stats) {
+			this.showStats(opts);
+			return;
+		}
+		this.showSnapshot(opts);
+	};
+	showSnapshot = (opts) => {
+		const snapshot = this.usageManager.getSnapshot();
+		if (opts.json) {
+			console.log(JSON.stringify({
+				ok: Boolean(snapshot),
+				mode: "snapshot",
+				path: this.usageManager.snapshotPath,
+				snapshot
+			}, null, 2));
+			process.exitCode = 0;
+			return;
+		}
+		if (!snapshot) {
+			console.log([
+				"No LLM usage snapshot recorded yet.",
+				`Snapshot path: ${this.usageManager.snapshotPath}`,
+				"Run `nextclaw agent -m \"ping\"` or use the local UI once, then retry `nextclaw usage`."
+			].join("\n"));
+			process.exitCode = 0;
+			return;
+		}
+		console.log(this.renderSnapshot(snapshot));
+		process.exitCode = 0;
+	};
+	showHistory = (opts) => {
+		const records = this.usageManager.getHistory(opts.limit);
+		if (opts.json) {
+			console.log(JSON.stringify({
+				ok: records.length > 0,
+				mode: "history",
+				path: this.usageManager.historyPath,
+				limit: this.usageManager.resolveHistoryLimit(opts.limit),
+				records
+			}, null, 2));
+			process.exitCode = 0;
+			return;
+		}
+		if (records.length === 0) {
+			console.log([
+				"No LLM usage history recorded yet.",
+				`History path: ${this.usageManager.historyPath}`,
+				"Run `nextclaw agent -m \"ping\"` or use the local UI once, then retry `nextclaw usage --history`."
+			].join("\n"));
+			process.exitCode = 0;
+			return;
+		}
+		console.log(this.renderHistory(records));
+		process.exitCode = 0;
+	};
+	showStats = (opts) => {
+		const stats = this.usageManager.getStats();
+		if (opts.json) {
+			console.log(JSON.stringify({
+				ok: stats.totalRecords > 0,
+				mode: "stats",
+				path: this.usageManager.historyPath,
+				stats
+			}, null, 2));
+			process.exitCode = 0;
+			return;
+		}
+		if (stats.totalRecords === 0) {
+			console.log([
+				"No LLM usage history recorded yet.",
+				`History path: ${this.usageManager.historyPath}`,
+				"Run `nextclaw agent -m \"ping\"` or use the local UI once, then retry `nextclaw usage --stats`."
+			].join("\n"));
+			process.exitCode = 0;
+			return;
+		}
+		console.log(this.renderStats(stats));
+		process.exitCode = 0;
+	};
+	renderSnapshot = (snapshot) => {
+		const lines = [
+			"Latest LLM usage snapshot",
+			`Observed at: ${snapshot.observedAt}`,
+			`Source: ${snapshot.source}`,
+			`Model: ${snapshot.model ?? "unknown"}`,
+			`Prompt tokens: ${snapshot.summary.promptTokens}`,
+			`Completion tokens: ${snapshot.summary.completionTokens}`,
+			`Total tokens: ${snapshot.summary.totalTokens}`,
+			`Cached tokens: ${snapshot.summary.cachedTokens}`,
+			`Cache hit: ${snapshot.summary.cacheHit ? "yes" : "no"}`,
+			`Snapshot path: ${this.usageManager.snapshotPath}`
+		];
+		if (snapshot.summary.cacheMetricKeys.length > 0) lines.push(`Cache metric keys: ${snapshot.summary.cacheMetricKeys.join(", ")}`);
+		if (Object.keys(snapshot.usage).length > 0) lines.push("", "Raw usage:", JSON.stringify(snapshot.usage, null, 2));
+		return lines.join("\n");
+	};
+	renderHistory = (records) => {
+		const lines = [
+			"Recent LLM usage history",
+			`History path: ${this.usageManager.historyPath}`,
+			`Showing: ${records.length} record(s)`,
+			""
+		];
+		for (const [index, record] of records.entries()) lines.push(`${index + 1}. ${record.observedAt} | source=${record.source} | model=${record.model ?? "unknown"} | total=${record.summary.totalTokens} | cached=${record.summary.cachedTokens} | cache-hit=${record.summary.cacheHit ? "yes" : "no"}`);
+		return lines.join("\n");
+	};
+	renderStats = (stats) => {
+		const lines = [
+			"LLM usage history stats",
+			`History path: ${this.usageManager.historyPath}`,
+			`Records: ${stats.totalRecords}`,
+			`Usage records: ${stats.usageRecordCount}`,
+			`Empty usage records: ${stats.emptyUsageRecordCount}`,
+			`Prompt-bearing records: ${stats.promptTokenRecordCount}`,
+			`Oldest observed at: ${stats.oldestObservedAt ?? "n/a"}`,
+			`Latest observed at: ${stats.latestObservedAt ?? "n/a"}`,
+			`Prompt tokens: ${stats.totalPromptTokens}`,
+			`Completion tokens: ${stats.totalCompletionTokens}`,
+			`Total tokens: ${stats.totalTokens}`,
+			`Cached tokens: ${stats.totalCachedTokens}`,
+			`Cache hit records: ${stats.cacheHitRecords}/${stats.promptTokenRecordCount} (${this.toPercent(stats.cacheHitRate)})`,
+			`Cache token rate: ${this.toPercent(stats.tokenCacheRate)}`
+		];
+		if (stats.sources.length > 0) lines.push(`Sources: ${stats.sources.map((item) => `${item.value}=${item.count}`).join(", ")}`);
+		if (stats.models.length > 0) lines.push(`Models: ${stats.models.map((item) => `${item.value}=${item.count}`).join(", ")}`);
+		return lines.join("\n");
+	};
+	toPercent = (value) => {
+		return `${(value * 100).toFixed(1)}%`;
+	};
+};
+//#endregion
+export { LlmUsageCommandService };
+
+//# sourceMappingURL=llm-usage-command.service.js.map

package/dist/services/usage/llm-usage-command.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-usage-command.service.js","names":[],"sources":["../../../src/services/usage/llm-usage-command.service.ts"],"sourcesContent":["import type { UsageCommandOptions } from \"@nextclaw-service/types/cli.types.js\";\nimport {\n  LlmUsageManager,\n  type LlmUsageStats,\n} from \"@nextclaw/kernel\";\n\nexport class LlmUsageCommandService {\n  private readonly usageManager: LlmUsageManager;\n\n  constructor(deps: {\n    usageManager?: LlmUsageManager;\n  } = {}) {\n    this.usageManager = deps.usageManager ?? new LlmUsageManager();\n  }\n\n  readonly show = async (opts: UsageCommandOptions = {}): Promise<void> => {\n    if (opts.history && opts.stats) {\n      console.error(\"Choose only one usage mode: `--history` or `--stats`.\");\n      process.exitCode = 1;\n      return;\n    }\n    if (opts.history) {\n      this.showHistory(opts);\n      return;\n    }\n    if (opts.stats) {\n      this.showStats(opts);\n      return;\n    }\n    this.showSnapshot(opts);\n  };\n\n  private readonly showSnapshot = (opts: UsageCommandOptions): void => {\n    const snapshot = this.usageManager.getSnapshot();\n    if (opts.json) {\n      console.log(JSON.stringify({ ok: Boolean(snapshot), mode: \"snapshot\", path: this.usageManager.snapshotPath, snapshot }, null, 2));\n      process.exitCode = 0;\n      return;\n    }\n    if (!snapshot) {\n      console.log([\n        \"No LLM usage snapshot recorded yet.\",\n        `Snapshot path: ${this.usageManager.snapshotPath}`,\n        \"Run `nextclaw agent -m \\\"ping\\\"` or use the local UI once, then retry `nextclaw usage`.\",\n      ].join(\"\\n\"));\n      process.exitCode = 0;\n      return;\n    }\n    console.log(this.renderSnapshot(snapshot));\n    process.exitCode = 0;\n  };\n\n  private readonly showHistory = (opts: UsageCommandOptions): void => {\n    const records = this.usageManager.getHistory(opts.limit);\n    if (opts.json) {\n      console.log(JSON.stringify({\n        ok: records.length > 0,\n        mode: \"history\",\n        path: this.usageManager.historyPath,\n        limit: this.usageManager.resolveHistoryLimit(opts.limit),\n        records,\n      }, null, 2));\n      process.exitCode = 0;\n      return;\n    }\n    if (records.length === 0) {\n      console.log([\n        \"No LLM usage history recorded yet.\",\n        `History path: ${this.usageManager.historyPath}`,\n        \"Run `nextclaw agent -m \\\"ping\\\"` or use the local UI once, then retry `nextclaw usage --history`.\",\n      ].join(\"\\n\"));\n      process.exitCode = 0;\n      return;\n    }\n    console.log(this.renderHistory(records));\n    process.exitCode = 0;\n  };\n\n  private readonly showStats = (opts: UsageCommandOptions): void => {\n    const stats = this.usageManager.getStats();\n    if (opts.json) {\n      console.log(JSON.stringify({ ok: stats.totalRecords > 0, mode: \"stats\", path: this.usageManager.historyPath, stats }, null, 2));\n      process.exitCode = 0;\n      return;\n    }\n    if (stats.totalRecords === 0) {\n      console.log([\n        \"No LLM usage history recorded yet.\",\n        `History path: ${this.usageManager.historyPath}`,\n        \"Run `nextclaw agent -m \\\"ping\\\"` or use the local UI once, then retry `nextclaw usage --stats`.\",\n      ].join(\"\\n\"));\n      process.exitCode = 0;\n      return;\n    }\n    console.log(this.renderStats(stats));\n    process.exitCode = 0;\n  };\n\n  private readonly renderSnapshot = (snapshot: NonNullable<ReturnType<LlmUsageManager[\"getSnapshot\"]>>): string => {\n    const lines = [\n      \"Latest LLM usage snapshot\",\n      `Observed at: ${snapshot.observedAt}`,\n      `Source: ${snapshot.source}`,\n      `Model: ${snapshot.model ?? \"unknown\"}`,\n      `Prompt tokens: ${snapshot.summary.promptTokens}`,\n      `Completion tokens: ${snapshot.summary.completionTokens}`,\n      `Total tokens: ${snapshot.summary.totalTokens}`,\n      `Cached tokens: ${snapshot.summary.cachedTokens}`,\n      `Cache hit: ${snapshot.summary.cacheHit ? \"yes\" : \"no\"}`,\n      `Snapshot path: ${this.usageManager.snapshotPath}`,\n    ];\n    if (snapshot.summary.cacheMetricKeys.length > 0) {\n      lines.push(`Cache metric keys: ${snapshot.summary.cacheMetricKeys.join(\", \")}`);\n    }\n    if (Object.keys(snapshot.usage).length > 0) {\n      lines.push(\"\", \"Raw usage:\", JSON.stringify(snapshot.usage, null, 2));\n    }\n    return lines.join(\"\\n\");\n  };\n\n  private readonly renderHistory = (records: ReturnType<LlmUsageManager[\"getHistory\"]>): string => {\n    const lines = [\n      \"Recent LLM usage history\",\n      `History path: ${this.usageManager.historyPath}`,\n      `Showing: ${records.length} record(s)`,\n      \"\",\n    ];\n    for (const [index, record] of records.entries()) {\n      lines.push(\n        `${index + 1}. ${record.observedAt} | source=${record.source} | model=${record.model ?? \"unknown\"} | total=${record.summary.totalTokens} | cached=${record.summary.cachedTokens} | cache-hit=${record.summary.cacheHit ? \"yes\" : \"no\"}`\n      );\n    }\n    return lines.join(\"\\n\");\n  };\n\n  private readonly renderStats = (stats: LlmUsageStats): string => {\n    const lines = [\n      \"LLM usage history stats\",\n      `History path: ${this.usageManager.historyPath}`,\n      `Records: ${stats.totalRecords}`,\n      `Usage records: ${stats.usageRecordCount}`,\n      `Empty usage records: ${stats.emptyUsageRecordCount}`,\n      `Prompt-bearing records: ${stats.promptTokenRecordCount}`,\n      `Oldest observed at: ${stats.oldestObservedAt ?? \"n/a\"}`,\n      `Latest observed at: ${stats.latestObservedAt ?? \"n/a\"}`,\n      `Prompt tokens: ${stats.totalPromptTokens}`,\n      `Completion tokens: ${stats.totalCompletionTokens}`,\n      `Total tokens: ${stats.totalTokens}`,\n      `Cached tokens: ${stats.totalCachedTokens}`,\n      `Cache hit records: ${stats.cacheHitRecords}/${stats.promptTokenRecordCount} (${this.toPercent(stats.cacheHitRate)})`,\n      `Cache token rate: ${this.toPercent(stats.tokenCacheRate)}`,\n    ];\n    if (stats.sources.length > 0) {\n      lines.push(`Sources: ${stats.sources.map((item) => `${item.value}=${item.count}`).join(\", \")}`);\n    }\n    if (stats.models.length > 0) {\n      lines.push(`Models: ${stats.models.map((item) => `${item.value}=${item.count}`).join(\", \")}`);\n    }\n    return lines.join(\"\\n\");\n  };\n\n  private readonly toPercent = (value: number): string => {\n    return `${(value * 100).toFixed(1)}%`;\n  };\n}\n"],"mappings":"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"}

package/dist/stores/companion-runtime.store.d.ts

@@ -0,0 +1,16 @@
+//#region src/stores/companion-runtime.store.d.ts
+type CompanionRuntimeState = {
+  pid: number;
+  startedAt: string;
+  baseUrl: string;
+};
+declare class CompanionRuntimeStore {
+  get path(): string;
+  readonly read: () => CompanionRuntimeState | null;
+  readonly write: (state: CompanionRuntimeState) => void;
+  readonly clear: () => void;
+}
+declare const companionRuntimeStore: CompanionRuntimeStore;
+//#endregion
+export { CompanionRuntimeState, CompanionRuntimeStore, companionRuntimeStore };
+//# sourceMappingURL=companion-runtime.store.d.ts.map

package/dist/stores/companion-runtime.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"companion-runtime.store.d.ts","names":[],"sources":["../../src/stores/companion-runtime.store.ts"],"mappings":";KAIY,qBAAA;EACV,GAAA;EACA,SAAA;EACA,OAAA;AAAA;AAAA,cAGW,qBAAA;EAAA,IACP,IAAA,CAAA;EAAA,SAIK,IAAA,QAAW,qBAAA;EAAA,SAWX,KAAA,GAAS,KAAA,EAAO,qBAAA;EAAA,SAKhB,KAAA;AAAA;AAAA,cAOE,qBAAA,EAAqB,qBAAA"}

package/dist/stores/companion-runtime.store.js

@@ -0,0 +1,29 @@
+import { getRunPath } from "@nextclaw/core";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+//#region src/stores/companion-runtime.store.ts
+var CompanionRuntimeStore = class {
+	get path() {
+		return resolve(getRunPath(), "companion.json");
+	}
+	read = () => {
+		if (!existsSync(this.path)) return null;
+		try {
+			return JSON.parse(readFileSync(this.path, "utf-8"));
+		} catch {
+			return null;
+		}
+	};
+	write = (state) => {
+		mkdirSync(resolve(this.path, ".."), { recursive: true });
+		writeFileSync(this.path, JSON.stringify(state, null, 2));
+	};
+	clear = () => {
+		if (existsSync(this.path)) rmSync(this.path, { force: true });
+	};
+};
+const companionRuntimeStore = new CompanionRuntimeStore();
+//#endregion
+export { CompanionRuntimeStore, companionRuntimeStore };
+
+//# sourceMappingURL=companion-runtime.store.js.map

package/dist/stores/companion-runtime.store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"companion-runtime.store.js","names":[],"sources":["../../src/stores/companion-runtime.store.ts"],"sourcesContent":["import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport { getRunPath } from \"@nextclaw/core\";\n\nexport type CompanionRuntimeState = {\n  pid: number;\n  startedAt: string;\n  baseUrl: string;\n};\n\nexport class CompanionRuntimeStore {\n  get path(): string {\n    return resolve(getRunPath(), \"companion.json\");\n  }\n\n  readonly read = (): CompanionRuntimeState | null => {\n    if (!existsSync(this.path)) {\n      return null;\n    }\n    try {\n      return JSON.parse(readFileSync(this.path, \"utf-8\")) as CompanionRuntimeState;\n    } catch {\n      return null;\n    }\n  };\n\n  readonly write = (state: CompanionRuntimeState): void => {\n    mkdirSync(resolve(this.path, \"..\"), { recursive: true });\n    writeFileSync(this.path, JSON.stringify(state, null, 2));\n  };\n\n  readonly clear = (): void => {\n    if (existsSync(this.path)) {\n      rmSync(this.path, { force: true });\n    }\n  };\n}\n\nexport const companionRuntimeStore = new CompanionRuntimeStore();\n"],"mappings":";;;;AAUA,IAAa,wBAAb,MAAmC;CACjC,IAAI,OAAe;AACjB,SAAO,QAAQ,YAAY,EAAE,iBAAiB;;CAGhD,aAAoD;AAClD,MAAI,CAAC,WAAW,KAAK,KAAK,CACxB,QAAO;AAET,MAAI;AACF,UAAO,KAAK,MAAM,aAAa,KAAK,MAAM,QAAQ,CAAC;UAC7C;AACN,UAAO;;;CAIX,SAAkB,UAAuC;AACvD,YAAU,QAAQ,KAAK,MAAM,KAAK,EAAE,EAAE,WAAW,MAAM,CAAC;AACxD,gBAAc,KAAK,MAAM,KAAK,UAAU,OAAO,MAAM,EAAE,CAAC;;CAG1D,cAA6B;AAC3B,MAAI,WAAW,KAAK,KAAK,CACvB,QAAO,KAAK,MAAM,EAAE,OAAO,MAAM,CAAC;;;AAKxC,MAAa,wBAAwB,IAAI,uBAAuB"}

package/dist/stores/local-ui-runtime.store.d.ts

@@ -0,0 +1,26 @@
+import { Config } from "@nextclaw/core";
+import { RemoteRuntimeState } from "@nextclaw/remote";
+
+//#region src/stores/local-ui-runtime.store.d.ts
+type LocalUiRuntimeState = {
+  pid: number;
+  startedAt: string;
+  uiUrl: string;
+  apiUrl: string;
+  uiHost?: string;
+  uiPort?: number;
+  remote?: RemoteRuntimeState;
+};
+declare class LocalUiRuntimeStore {
+  get path(): string;
+  readonly read: () => LocalUiRuntimeState | null;
+  readonly write: (state: LocalUiRuntimeState) => void;
+  readonly update: (updater: (state: LocalUiRuntimeState) => LocalUiRuntimeState) => LocalUiRuntimeState | null;
+  readonly clear: () => void;
+  readonly clearIfOwnedByProcess: (pid?: number) => void;
+  readonly writeCurrentProcess: (uiConfig: Pick<Config["ui"], "host" | "port">, pid?: number) => LocalUiRuntimeState;
+}
+declare const localUiRuntimeStore: LocalUiRuntimeStore;
+//#endregion
+export { LocalUiRuntimeState, LocalUiRuntimeStore, localUiRuntimeStore };
+//# sourceMappingURL=local-ui-runtime.store.d.ts.map